File, save and transfer problems
Most file failures are one of four things: the remote account is not allowed to do it, the server does not implement it, the item changed under you, or the transport went away mid-operation. They look similar in passing and need different responses.
Symptoms
- A folder will not open, or opens empty when you expect contents.
- Saving is disabled, or a save is refused.
- A rename, move or delete is refused even though you can see the item.
- A transfer fails partway, or the destination already exists.
- An operation reports an uncertain outcome rather than success or failure.
Checks
1. Is the capability there at all? Files needs a files service on the connection. Creating, renaming and deleting arrive as a group; moving, downloading and uploading each arrive separately. A missing group is shown as unavailable, so read-only Files is a provider boundary and not a permissions problem — see Providers and device detection.
2. Is it a remote permission? The account you connected with decides what you may do. A folder you can list but not write to fails at the write, not at the listing. Check ownership and mode on the host.
3. Did the item change? Every entry carries a revision. If a move, rename or delete is refused because the revision is stale, something changed the item after you listed it. Refresh the folder and look again before repeating the action — the refusal is what stops the operation landing on a different file than the one you selected.
4. Is the connection still alive? After a drop, listings are stale and writes are disabled. Reconnect, then refresh. Do not treat post-drop errors as file errors.
5. Does the destination already exist? Transfers and renames refuse to replace silently. That is a deliberate design, and the message is telling you the truth about the destination.
6. Was the outcome uncertain? An operation whose acknowledgement was lost is reported as uncertain rather than as success or failure. Verify the current state on the host before retrying — a retry of a write that already landed is a second write.
Resolution
| Situation | What to do |
|---|---|
| Read-only Files | The provider does not advertise the mutation methods. Use a connection that does. |
| Permission denied | Fix ownership or mode on the host, or connect as an account that may perform the action. |
| Stale revision | Refresh the folder, confirm the item is the one you meant, then repeat the action. |
| Save disabled in the editor | The files capability is unavailable or the connection dropped. Your text is retained — reconnect, then save. |
| Save conflict | Compare deliberately and choose. Do not overwrite to make the prompt go away; the other version exists for a reason. |
| Destination exists | Rename, choose another destination, or remove the existing item explicitly. |
| Transfer interrupted | Restart it. Transfers do not resume, and a partial file at the destination is yours to clean up. |
| Folder transfer partly done | Check what completed before restarting; directory structure may already exist. |
| Uncertain outcome | Inspect the host, then decide. Never assume the convenient result. |
Unsaved editor text is never discarded to reflect a remote failure. If saving is unavailable, the safest immediate step is to copy your changes somewhere durable, then restore the connection and save.
When to report an issue
Report when the behaviour contradicts these rules: a save that reports success but does not change the file, a listing that is persistently wrong after a refresh, a transfer that corrupts content rather than failing, a revision refusal on an item nothing touched, or an uncertain outcome that repeats reliably.
Include the ShellCanvas version, your platform, the server's SSH and SFTP implementation, the operation, the exact visible error, file size and kind for transfer problems, and the shortest sequence that reproduces it. Describe paths in a redacted form and never attach remote file content.
Related guides
- Browse and manage files — the normal path.
- Transfer files — download and upload behaviour, including limits.
- Edit text files — drafts, saving and conflicts.
- Recover from a dropped connection — what to do after a drop.