> For the complete documentation index, see [llms.txt](https://docs.stackai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stackai.com/guides-and-quickstarts/interfaces-and-end-user-experiences/let-an-agent-work-with-uploaded-files/troubleshoot-uploaded-files-and-downloads.md).

# Troubleshoot uploaded files and downloads

Practical checks for file uploads, agent access, generated downloads, and interface behavior.

Start with a small file whose contents you can verify. Follow it through the interface, the agent's inputs, its tool result, and the final download.

{% embed url="<https://1957915746-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSQ1Sgy933krTyK0S4JpP%2Fuploads%2FqVcX3HJ36anviWBXn7VD%2FStackAI-Uploaded-Files-Troubleshooting-Alice.mp4?alt=media&token=9bc16430-32fd-4ffc-8298-cc2594eacacc>" %}

## The paperclip is missing, or the uploaded file never reaches the agent

1. In **Interface → Configuration**, enable **Show attachment icon**.
2. In **Fields**, confirm the **Files** input is selected. Showing the icon does not select that input automatically.
3. In Workflow Builder, connect Files to the agent and insert its output in the agent's **Prompt** using the reference picker.

<figure><img src="https://1957915746-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSQ1Sgy933krTyK0S4JpP%2Fuploads%2FZ9qxuDAjrSwc9tCKUQ3n%2Fuploaded-files-08-interface-fields-focused.png?alt=media&amp;token=7ec5853a-502c-431e-bc91-e20a59a907fd" alt="Interface Files mapping and required-field controls" width="600"><figcaption><p>Interface Files mapping and required-field controls</p></figcaption></figure>

Check the node ID as well as its alias. If there are several Files inputs, confirm the upload reaches the one referenced by the agent. **Required** controls whether users must provide a file; it does not enable file access.

## The upload is still processing

Wait for the interface's upload state to finish before sending. If it remains stuck, inspect the visible error, check the connection, and try one small file. Repeatedly sending the same request does not complete an unfinished upload.

<figure><img src="https://1957915746-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSQ1Sgy933krTyK0S4JpP%2Fuploads%2F7Vukk5syoqvbpglgBhcs%2Fuploaded-files-10-chat-upload.png?alt=media&amp;token=46372482-83fb-4961-98c3-234fdd834741" alt="Attached file in Draft Preview" width="760"><figcaption><p>Attached file in Draft Preview</p></figcaption></figure>

An accepted upload proves that the file was transferred. It does not prove that a parser or tool can read it.

## The agent sees a filename but cannot read or analyze the file

1. Confirm **Settings → Knowledge & Inputs → File Access** is on.
2. Confirm **Terminal** from **StackAI Computer** appears in the agent's tools, with its required **Command** input configured. The walkthrough uses AI auto-fill.
3. Ask the agent to inspect the uploaded file before answering. Open its actual tool result to see whether it found and read the file.

<figure><img src="https://1957915746-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSQ1Sgy933krTyK0S4JpP%2Fuploads%2FzSe5viwb9QU0eTWQafj9%2Fuploaded-files-05-file-access-setting.png?alt=media&amp;token=f9e8e5cc-f696-463c-a58d-08d94fa4dddd" alt="File Access enabled in the agent settings" width="760"><figcaption><p>File Access enabled in the agent settings</p></figcaption></figure>

If Terminal is unavailable in your environment, ask your workspace administrator about its availability. For a text-only summary, consider passing **Full Parsed Text** to the Prompt instead.

If the result reports a reading or parsing failure, check the file format and the limit shown by that upload control. Try an unencrypted, supported file. Scanned PDFs may need OCR, and a text extraction step can miss images or layout. Renaming a file extension does not convert its contents. See [File Inputs, Supported Formats, and Size Limits](https://docs.stackai.com/technical-reference/files-knowledge-and-retrieval/file-inputs-supported-formats-and-size-limits.md).

## The answer looks right, but there is no usable download

1. Ask explicitly for a new file, including what it should contain.
2. In **Terminal → Configurations**, keep **Enable New Files** on. For the Terminal workflow in this guide, instruct the agent to save generated files under `/home/user/`.
3. Inspect the tool's returned files and the final answer. The agent should return the actual file link, rather than inventing a link or returning only a filename.
4. Check that the interface exposes the intended output.

<figure><img src="https://1957915746-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSQ1Sgy933krTyK0S4JpP%2Fuploads%2FlEOslAgwB9uiMKiXGjsc%2Fuploaded-files-07-new-files.png?alt=media&amp;token=ffea6d32-90f1-471e-8860-6fdd61b555ae" alt="Enable New Files switched on in Terminal" width="760"><figcaption><p>Enable New Files switched on in Terminal</p></figcaption></figure>

Open the download and check its contents. A table export can contain only the displayed summary, while a generated CSV can contain the cleaned source rows. If a download link has expired or the file was regenerated, create the result again and use its latest returned link.

## A follow-up loses track of the file

Continue in the same conversation and check the agent's conversation and memory settings. If the file is still unavailable, attach it again and make the question explicit. For a new conversation, a separate form submission, or an independent batch row, supply the required file again.

<figure><img src="https://1957915746-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSQ1Sgy933krTyK0S4JpP%2Fuploads%2FD9od1PknvQlvCKwQC8KJ%2Fuploaded-files-13-followup.png?alt=media&amp;token=8ec4021d-84b5-4b8e-b807-8c67225952c2" alt="Follow-up answer in the same conversation" width="760"><figcaption><p>Follow-up answer in the same conversation</p></figcaption></figure>

Do not assume that files or generated results are available across unrelated conversations. For related Terminal calls, reuse the environment returned by the earlier call when needed; a separate environment starts with separate working state.

## Draft Preview works, but the published assistant behaves differently

Confirm the edited project version completed the required publication process. Draft Preview uses the current draft; the released interface can still use an earlier version. Check the published Fields, attachment controls, and intended user's access. Test the published or embedded experience from the route users will actually use.

See [Publish a Chat Assistant](https://docs.stackai.com/guides-and-quickstarts/interfaces-and-end-user-experiences/publish-a-chat-assistant.md) and [Interface authentication and access](https://docs.stackai.com/guides-and-quickstarts/interfaces-and-end-user-experiences/interface-authentication-and-access.md).

## The calculation or file contents are wrong

Ask for the precise rule: which rows to include, which values to sum, and what the output should contain. Compare the answer with the source data and expanded tool result. For the walkthrough sample, **four confirmed signup rows** contain **eight seats**; those are different counts.

<figure><img src="https://1957915746-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSQ1Sgy933krTyK0S4JpP%2Fuploads%2F9Lx2VQvV7jTRLxEanGAg%2Fuploaded-files-11-tool-results.png?alt=media&amp;token=70cc9d98-55ba-406d-967f-382870ba4650" alt="Expanded tool results showing source rows and calculated totals" width="760"><figcaption><p>Expanded tool results showing source rows and calculated totals</p></figcaption></figure>

An executed command can still calculate the wrong thing. Review the actual result before using or sharing it.

## If you need help

Provide the project and interface type, whether the issue occurs in Draft Preview or the published release, the visible error, and a small non-sensitive example that reproduces it. Include the relevant tool result when available, and avoid sharing private download links or sensitive source files unnecessarily.

Return to [Let an agent work with uploaded files](https://docs.stackai.com/guides-and-quickstarts/interfaces-and-end-user-experiences/let-an-agent-work-with-uploaded-files.md) for the complete setup.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.stackai.com/guides-and-quickstarts/interfaces-and-end-user-experiences/let-an-agent-work-with-uploaded-files/troubleshoot-uploaded-files-and-downloads.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
