Common Issues

Connection issues

Authentication fails when entering API credentials

Double-check that you're using the correct Client ID, Client Secret, and Enterprise ID (or User ID) from your Box Developer App. Make sure the app has been authorized for your enterprise in the Box Admin Console — apps using Client Credentials Grant require explicit admin approval before they can access content.

Connection succeeds but no files are returned

The service account or app user associated with your Box Developer App may not have access to the target folder. In Box, sharing permissions are not inherited by API apps automatically. Make sure the app's service account has been added as a collaborator on the folder you specified.

Missing data

Some files in the folder are not appearing in the output

Box Data Extract only processes file types that Box supports for text representation. Files in unsupported formats (e.g., some image types or proprietary formats) may be skipped silently. Check whether the missing files are in a supported format such as PDF, DOCX, or TXT.

Also verify whether the files are in a subfolder rather than the root folder — if Recursive is not enabled, only files directly in the specified folder are processed.

AI entity returns empty or null results for some files

Box AI may return empty responses for files that are too short, contain only images, or are in a format that Box AI cannot parse. Check the source file directly in Box to confirm it has readable text content. For scanned documents, OCR must be enabled in your Box account for AI to process them.

Permission errors

"Insufficient permissions" error when accessing a folder

Your Box app's service account needs at least Viewer access to the folder. Go to the folder in Box, open sharing settings, and add the service account email as a collaborator. For AI entities, the app also needs Box AI to be enabled on your account plan.

Box AI features return a permissions or plan error

Box AI (Ask, Extract, Extract Structured) is only available on plans that include Box AI. If you see an error related to AI access, confirm with your Box admin that your account has the Box AI add-on enabled.

Data discrepancies

Extracted text looks truncated or incomplete

Box's text representation API has limits on the amount of text it returns per file. Very long documents may be truncated. For full-document processing, consider splitting large files before storing them in Box, or use the AI extract entity with a targeted prompt to pull only the fields you need.

AI answers vary between runs for the same document

Box AI responses can be non-deterministic — the same prompt on the same document may return slightly different phrasing across runs. If consistency is important, use Stream AI extract structured folders with a fixed schema rather than free-form prompts.

Rate limits

Data flow times out or fails partway through a large folder

Box's API enforces rate limits on both the representation and AI endpoints. If you're processing a folder with many files, the data flow may slow down or hit limits. Try reducing the folder size by splitting files across multiple folders, or run separate data flows for different subfolders rather than enabling Recursive on a very large tree.