Troubleshooting
Common issues and solutions related to the agent filesystem.
The Filesystem Volume toggle is missing or grayed out on the agent edit page
You do not have permission to change the agent. The toggle is only active for workspace admins, the agent's owner, and people with Editor or Admin access to the specific agent. If you only have Viewer or Can Execute access, you can see the toggle's current state but not change it. Ask the owner or a workspace admin to flip it for you, or ask for Editor access.
You are on the wrong page. The toggle lives on the agent's edit page, just above Channel Mappings. If you are on the agent's chat page or the agent list, you will not see it. Go to Agents, click the agent, and scroll down.
The edit page did not finish loading. If the rest of the form is still showing skeleton placeholders, the toggle has not rendered yet. Wait a moment for the page to finish loading and try again.
I turned the filesystem on but the agent says it does not have file tools
The agent already had an open chat when you turned it on. Tools are attached when a chat starts. Open a new chat with the agent — the file tools will be available on the new session. Existing chats continue to use the toolset they were initialized with.
The page is cached. If the agent is running in a background job or a separate tab, refresh or restart the session to pick up the new configuration.
The change did not save. Revisit the agent's edit page and confirm the switch is still in the on position. If it slid back to off, the update failed — see the next entry.
The toggle flips on and then slides back to off
You do not have edit permission on the agent. The page performs the update under your session, and the permission check happens at save time. If you lack permission, the update is rejected and the switch rolls back. Ask an owner or admin to flip it.
Your session has expired. Sign out and back in, then try again.
The server returned an error. A message should appear at the bottom of the screen explaining what went wrong. If it mentions "storage" or "database", the failure is infrastructure-side — retry once, and if it keeps failing, contact your workspace administrator with the exact text.
The agent reports "quota exceeded" when it tries to save a file
The agent has hit its 100 MB storage cap. Every agent can hold up to 100 MB total across all files. Once the cap is reached, new writes are refused until something is deleted. Ask the agent to list its largest files and delete the ones you no longer need. For example: "list every file in /logs/ and delete anything older than last week."
Disabling the filesystem does not free up the cap. Disabling is a soft switch that retains all files. If you need to reclaim space, enable the filesystem first, delete files through the agent, and then disable again if you want.
The agent reports "file too large" when saving
A single file cannot exceed 2 MB. The cap applies to the text the agent is trying to save, not to total storage. If the agent is trying to save a long document, ask it to split the content across multiple files. For example: "save the first third of this report to report-part-1.md, the next third to report-part-2.md, and the last third to report-part-3.md."
The agent reports "binary rejected" or will not save a download
The filesystem only stores text files. Images, PDFs, archives, spreadsheets in native binary formats, audio, and video are not allowed. If the agent tried to download a URL with fs_curl, the response must be text (HTML, JSON, YAML, CSV, plain text, markdown, source code, etc.). PDFs and images are rejected at write time.
The file extension does not match the actual content. The agent looks at the first bytes of the file to decide whether it is text. If a file has a .txt extension but contains binary bytes, it is still rejected. Ask the agent to convert the content to plain text first, or pick a different source.
The agent cannot fetch a URL with the download tool
The URL resolves to a private or internal address. The download tool blocks private IP ranges (corporate networks, loopback, local services) to prevent accidental data leaks. Public web addresses work. If you need to download from an internal system, use a custom tool that connects directly to the internal API instead of the filesystem download tool.
The URL points at the Assist storage service itself. The download tool also blocks the workspace's own Supabase storage host to prevent signed-URL recycling. Use the normal read tool or a signed link instead.
The URL is behind authentication. The download tool does not support authenticated endpoints, redirects through sign-in pages, or cookie-based sessions. Use a custom tool with appropriate credentials.
The URL returned non-text content. See the previous entry about binary rejection.
Files disappeared when I disabled the filesystem
They did not. Disabling is a soft switch. Every file is retained exactly as it was. Turn the filesystem back on and the files reappear in place. If they are still missing after re-enabling, the agent may have been looking at a different path than you expect — ask the agent to list every file it can see and work from that.
My colleague cannot see the files even though I shared the agent with them
They have Viewer, not Can Execute. Viewer is a strict read-only level that lets them see the agent exists but does not let them start a new chat. They cannot ask the agent to read or search files because they cannot talk to the agent at all. Raise them to Can Execute on the Workspace Permissions page.
They are in a different workspace. Sharing is scoped to one workspace. Confirm that both of you are members of the same workspace.
They were added to a group, but the group does not have access to this specific agent. Check whether the permission was granted to the group directly, or whether they were added to the group after the fact. Re-add the person directly to the agent if needed.
The permission was only granted to a group they are not in. On the Resources page, check the exact permissions list for the agent. If the person is not there and not a member of any group in the list, they do not have access.
The agent writes files in one chat but cannot find them in a new chat with the same agent
Look for a typo in the path. Files are referenced by exact path, so /notes/plan.md and /Notes/plan.md are different files. Ask the agent to list every file it can see and work from that list.
Another user deleted the file between chats. Anyone with Can Execute or higher can ask the agent to delete files. If a file disappears unexpectedly, check whether a collaborator has been working with the same agent.
The filesystem was disabled and then re-enabled. This is safe — files are retained — but if the agent was told the wrong state in between, it may report files as missing. Ask the agent to explicitly list files now.
Still need help?
If your issue is not covered here, contact your workspace administrator. They can see every agent, every file, and every permission in the workspace, and can investigate access or storage issues from the admin panel.