# Common Issues

## Connection issues

<details>

<summary>Authentication fails when entering API credentials</summary>

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.

</details>

<details>

<summary>Connection succeeds but no files are returned</summary>

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.

</details>

## Missing data

<details>

<summary>Some files in the folder are not appearing in the output</summary>

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.

</details>

<details>

<summary>AI entity returns empty or null results for some files</summary>

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.

</details>

## Permission errors

<details>

<summary>"Insufficient permissions" error when accessing a folder</summary>

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.

</details>

<details>

<summary>Box AI features return a permissions or plan error</summary>

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.

</details>

## Data discrepancies

<details>

<summary>Extracted text looks truncated or incomplete</summary>

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.

</details>

<details>

<summary>AI answers vary between runs for the same document</summary>

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.

</details>

## Rate limits

<details>

<summary>Data flow times out or fails partway through a large folder</summary>

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.

</details>