> For the complete documentation index, see [llms.txt](https://help.filed.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.filed.com/reference/troubleshooting/system-issue-or-error.md). # System issue or error ## What a system issue means A system issue means one of the pipeline sub-tasks reached a failed state. Sub-tasks include steps such as document conversion, tax data extraction, the data-entry bot session, and entry validation. When any of these fail, Filed marks the overall return with a system issue status and surfaces as much diagnostic context as possible through the pop-up message. A system error is distinct from a Paused state. Paused means the workflow is waiting for user input. A system error means something went wrong during automated processing. ## Read the pop-up message first The pop-up message is the primary diagnostic tool. It describes what failed and often tells you exactly what action to take - whether that is re-triggering, correcting a credential, replacing a document, or contacting support. Always read the message before doing anything else. ## Common error types Errors generally fall into two categories: transient system errors that clear on a re-trigger, and specific blocking errors that require a targeted fix. ### Transient processing failure A one-off infrastructure event, a temporary queue delay, or a brief service interruption can cause a sub-task to fail even though nothing is permanently wrong. These errors typically do not repeat when the job is re-run. Clicking Re-run Tax Prep is the first action for any system error where the pop-up does not identify a specific cause. Many errors resolve on the second attempt. ### Data entry errors When the data-entry bot session fails, Filed records an error code that describes the specific failure. The pop-up message and the return detail page surface this code. The known error codes and their plain-language meanings are: **Invalid credentials** - The credentials Filed is using to log into the tax software are incorrect or have expired. Filed cannot authenticate and therefore cannot enter data. Check the credentials stored in Filed's Connected Tax Software settings and update them if they have changed. **Captcha failed** - The tax software presented a captcha challenge that the automated session could not complete. This is a transient error in most cases. Click Re-run Tax Prep to retry. **Client not found** - The data-entry bot opened the tax software but could not locate the client record for this return. The client may not exist under the expected ID, may not be rolled over to the current tax year, or the client ID stored in Filed may be incorrect. Verify the client exists and is accessible in the tax software, then re-trigger. **Client already open** - The client's return is currently open in the tax software in another session or on another machine. The bot cannot enter data while the return is locked. Close the return in the tax software, then click Re-run Tax Prep. **Not registered** - The tax software account or the specific client is not registered or licensed in a way that allows access. This is a software-side configuration issue rather than a Filed issue. Review the registration or license status in the tax software, then re-trigger. **Timeout** - The bot session exceeded the allowed time limit for a step, usually because the tax software was slow to respond or a screen took longer than expected to load. Click Re-run Tax Prep to retry. If timeouts recur consistently, contact support. **Unknown** - The bot encountered an error that does not match any of the recognized categories above. Click Re-run Tax Prep once. If the error recurs, contact support and include the full error message text so the engineering team can investigate. ### Document processing error If a source document could not be converted, classified, or extracted, it may be flagged as requiring manual review. This typically happens when a file is corrupted, in an unsupported format, or unreadable for another reason (such as a low-quality scan). The return cannot fully complete while the document is in this state. Check the documents on the client's binder for any flagged items. Replace corrupted or unreadable files with clean versions and re-trigger. ### Connection or sync error A connection job between Filed and the tax software or document management system can fail if the integration credentials are stale, the external service returned an error, or the sync was interrupted. When this happens, the Connected Software page in Filed typically shows an error indicator for the affected connection. Check the Connected Software page for any connection in an error state. Reconnect or re-authenticate as needed, then re-trigger the return. ## How to fix it Read the pop-up message first and follow any specific instructions it contains. If no specific instruction is given, click Re-run Tax Prep. For errors tied to credentials, documents, or connections, resolve the underlying cause first and then re-trigger. ## When to contact support Contact Filed support if: * Re-run Tax Prep has been attempted and the same error recurs * The error code shown is "unknown" and a second attempt does not clear it * The pop-up message references a situation not covered above Include the return ID, your tax software name, the full text of the error message, and the steps already tried. --- # 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://help.filed.com/reference/troubleshooting/system-issue-or-error.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.