Help The Google Gemini API I use cannot perform OCR recognition on the files I upload!

[xxH7r]

Self Checks

• I have searched for existing issues search for existing issues, including closed ones.
• I confirm that I am using English to submit this report (我已阅读并同意 Language Policy).
• [FOR CHINESE USERS] 请务必使用英文提交 Issue，否则会被关闭。谢谢！:)
• Please do not modify this template :) and fill in all the required fields.

1. Is this request related to a challenge you're experiencing? Tell me about your story.

My workflow is to upload a PDF file at the start node and then let Google Gemini's API do the OCR recognition. However, during the actual runtime, an error message is displayed:
Run failed: Invalid context structure: dify_model_identity='dify__file' id=None tenant_id='f621c54e-93e7-433d-a5e0-f7b4617b7c08' type=<FileType.DOCUMENT: 'document'> transfer_method=<FileTransferMethod.LOCAL_FILE: 'local_file'> remote_url='/files/7f9bbf11-15f2-4578-8794-6e8cf23a8e17/file-preview?timestamp=1761548582&nonce=b399870dbb11543f51c74781ca5aa92b&sign=xOVIGIwquACbZCcYRRMxcmh_hr06X14QkyT7eMrNmO4%3D' related_id='7f9bbf11-15f2-4578-8794-6e8cf23a8e17' filename='01-10.pdf' extension='.pdf' mime_type='application/pdf' size=8221329

2. Additional context or comments

The model's APIs have been correctly configured.
The configuration of the start node and gemini node is as follows.

[dosubot[bot]]

The "Invalid context structure" error usually means the file input passed to the Gemini OCR node doesn't match the strict format Dify expects. For Gemini and other multimodal models, Dify requires the file variable to be set as an Array[File] in the workflow, not just a single file object. Also, the file metadata must include all required fields, and the file URL should have a valid scheme (like http:// or https://).

Common fixes are: make sure your file input variable is configured as an array of files (Array[File]), check that the file object includes all necessary metadata, and ensure the file URL is complete and accessible. If you're self-hosting, there are known issues with context validation in some Dify versions that may require a patch or update. For some setups, setting the FILES_URL environment variable can help with file URL handling. More details and similar cases are discussed here.

If your workflow already uses Array[File] and you still see the error, double-check that the file content is actually being passed (not just the metadata or URL), as some plugins and nodes require the file bytes in a blob field, not just a reference. See this discussion for more on that.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[dosubot[bot]]

The error is happening because the file context passed to Gemini is incomplete—specifically, the file id is None and the remote_url is still a relative path (like /files/...). This means Dify is not applying your ngrok FILES_URL setting correctly, so Gemini cannot access the file externally.

Here’s what you should check:

1. Make sure you set the ngrok URL (e.g., https://xxxx.ngrok.io) as the FILES_URL environment variable in your Dify Docker .env file, not just in the Gemini model config.
2. After updating .env, fully restart all Dify Docker containers so the new setting takes effect.
3. When you upload a file and run the workflow, the remote_url in the error message should start with your ngrok URL (e.g., https://xxxx.ngrok.io/files/...). If it’s still a relative path, Dify is not picking up the new setting.

If you still see a relative path or id=None, double-check that you edited the correct .env file and that Docker Compose is using it. There was a recent change in Dify’s Docker setup that removed the default FILES_URL—so you must set it yourself for public file access to work source.

Once the file URLs are absolute and public, Gemini should be able to access them for OCR. If you continue to see id=None, there may be an issue with how the file is uploaded or passed through your workflow—make sure the file input is set as an array of files (Array[File]) and that you’re only uploading one file at a time, as multi-file uploads can sometimes cause issues source.

Let me know if the remote_url changes to a full ngrok URL after these steps!

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[xxH7r]

Because before this, there was no .env file in my folder, only a .env.example sample file, so in order to follow your advice, I created a new .env file and added a line: FILES_URL=my ngrok address, but it still reported an error: Run failed: Invalid context structure: dify_model_identity='dify__file' id=Nonetenant_id='f621c54e-93e7-433d-a5e0-f7b4617b7c08' type=<FileType.DOCUMENT: 'document'> Transfer Method =<FileTransferMethod.LOCAL_FILE: 'local_file'> remote_url='/files/6a2135e1-2886-40b9-a40f-8262b18bbbac/file-preview?timestamp=1761553977&nonce=e2be21fb721af4630f166a770bfc86a9&sign=UMHCsCYDXR_byw3NNnbtjlCECHPVhsea8Qfpo3N3QE0%3D' related_id='6a2135e1-2886-40b9-a40f-8262b18bbbac' filename='11-20.pdf' extension='.pdf' mime_type='application/pdf' size=8746213

[dosubot[bot]]

The error is happening because Dify isn't picking up your FILES_URL setting, so file URLs remain relative and the Gemini node can't access them. Here’s what you need to check:

1. Make sure your .env file is in the same directory as your docker-compose.yml file (usually the docker/ folder if you use Dify's Docker setup). If you put .env in the wrong place, Docker Compose won't load it and Dify won't see your FILES_URL setting.
2. The FILES_URL line in your .env file should look like this (replace with your actual ngrok URL, including https://):

FILES_URL=https://xxxx.ngrok.io

3. After saving the .env file, you must fully restart all Dify containers with:

docker-compose down && docker-compose up -d

If you skip this, the new environment variable won't be loaded.

4. After restarting, upload a new file and check if the error message now shows a remote_url starting with your ngrok address (e.g., https://xxxx.ngrok.io/files/...). If it’s still a relative path (starts with /files/...), Dify still isn’t seeing your FILES_URL setting.

If you still have issues, double-check for typos or extra spaces in your .env file, and make sure you’re not using localhost in the URL. If you use proxy software, turn it off while testing. For some setups, you may also need to set INTERNAL_FILES_URL in the .env file to the same ngrok URL, but usually FILES_URL is enough for external access.

This requirement is due to a recent change in Dify: there is no default FILES_URL anymore, so you must set it yourself for file URLs to work with external models like Gemini source source.

If you follow these steps and remote_url is still not absolute, let me know what your folder structure looks like and where you placed the .env file.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[xxH7r]

I have done it as you said, but still got the error: Run failed: invalid context structure: Run failed: Invalid context structure: dify_model_identity='dify__file' id=None tenant_id='f621c54e-93e7-433d-a5e0-f7b4617b7c08' type=<FileType.DOCUMENT: 'document'> transfer_method=<FileTransferMethod.LOCAL_FILE: 'local_file'> remote_url='https://niftiest-unresigned-rosario.ngrok-free.dev/files/d05199c1-1da8-493b-b065-c4da9974bbbe/file-preview?timestamp=1761555086&nonce=e67bbbec11846ec7c5a564a29862c109&sign=_qCrb1OOmGcEvKuckU_kxCVpveDAG2vH9GPlJChiMYM%3D' related_id='d05199c1-1da8-493b-b065-c4da9974bbbe' filename='01-10.pdf' extension='.pdf' mime_type='application/pdf' size=8221329
Another thing is that there is only FILES_URL in my .env file

[dosubot[bot]]

Your file URLs are now public, but the error persists because the file context passed to Gemini is still missing a valid id. This usually means the file upload step didn't fully register the file in Dify's database, or the workflow is passing incomplete file info to the Gemini node. This can happen if the file input variable isn't set up as an array of files, or if there's a recent bug in the file uploader logic.

To fix this, make sure:

• Your workflow's file input is configured as an array of files (Array[File]), even if you only upload one file.
• You upload the file through the Dify UI and select it in the workflow input form, not by pasting a URL or using a custom node.
• After uploading, check the workflow run details: the file object should have a non-null id and related_id. If id is still None, try deleting and recreating the file input node.

Recent changes in Dify's file uploader may have affected how file context is synchronized, which can cause this issue even if your config is correct (source). If you updated Dify recently, this could be the cause.

If you still see id=None after these checks, try restarting your browser and clearing the cache, then re-upload the file and run the workflow again. If the problem persists, it may be a temporary bug in the current Dify version's file handling logic (source).

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[xxH7r]

I have always set the upload file of the starting node to Array[File], but it still gives an error. Is there any other reason for the error? I just used cloudflare to create a temporary link, but it still gives an error:Run failed: Invalid context structure: dify_model_identity='dify__file' id=None tenant_id='f621c54e-93e7-433d-a5e0-f7b4617b7c08' type=<FileType.DOCUMENT: 'document'> transfer_method=<FileTransferMethod.LOCAL_FILE: 'local_file'> remote_url='https://updates-alan-peripherals-thursday.trycloudflare.com/files/6a3b1523-2a8e-4764-99c2-ef74d59e69b9/file-preview?timestamp=1761575233&nonce=957e0063d75cacf52932fdb0e3e98f1e&sign=NiOBnO-2zJxV1GZBqhUl7kG6J2Gjs5pWEnt2TjoCmpc%3D' related_id='6a3b1523-2a8e-4764-99c2-ef74d59e69b9' filename='01-10.pdf' extension='.pdf' mime_type='application/pdf' size=8221329

[dosubot[bot]]

There are a few additional reasons you might still see the "Invalid context structure" error with id=None even when using Array[File] and public URLs:

1. Your workflow's file upload feature must be enabled, and the allowed file types/extensions must include PDFs. If the file type or extension isn't allowed, or the file size exceeds the configured limit, the file won't be registered correctly and the id will be None (details).
2. In self-hosted Docker setups, missing environment variables for the unstructured API service (ETL_TYPE, UNSTRUCTURED_API_URL, UNSTRUCTURED_API_KEY) can cause this error when using uploaded files in LLM nodes. These are required for file upload functionality to work (details).
3. Recent Dify updates introduced stricter type validation for file uploads and changes to how file context is passed. If the file context is incomplete or not properly mapped (for example, missing the transfer_method field), the id can remain None and trigger this error (details, details).
4. Even with correct configuration, this can be a bug in the current Dify version's file upload or context propagation logic. This is a known issue, especially in recent self-hosted Docker versions (details, details).

Checklist:

• Make sure file upload is enabled in your workflow and PDFs are allowed.
• Check your .env for the required unstructured API variables.
• Try re-uploading the file after clearing your browser cache.
• If the problem persists, it may be a platform bug. As a workaround, some users have used the related_id field instead of id in downstream nodes, but this depends on node compatibility (details).

Let me know if you want help checking your workflow YAML or environment variable setup.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}