Troubleshooting

Start with the CLI’s version, authentication source, and local diagnostics:

aspect --version
aspect auth status
aspect doctor
aspect status

Add --json when collecting a result for a script. Commands report stable error codes as well as an explanation; use both to determine what to fix.

Installation

Symptom	What to check
`aspect` is not found	Open a new terminal after installation. On macOS/Linux, check that `~/.aspect/bin` is on `PATH`; on Windows, check `%USERPROFILE%\.aspect\bin`.
A documented flag is unknown	Check `aspect --version`, then `aspect <command> --help`. Use `aspect upgrade` to install the latest published release.
`release_unavailable` during upgrade	Check your connection and access to GitHub Releases, then retry.
`downgrade_refused`	Your installed version is newer than the latest public release. Keep it, unless you deliberately intend to install that older public version.

Authentication

Error or behavior	What to do
`not_logged_in`	Follow the message. On a workstation with the desktop app, open it and sign in. On a CLI-only machine, configure an API key.
`invalid_api_key`	Check that the key was copied correctly and has not been deleted. Create a replacement in Settings → API Keys if needed.
A supplied key appears to be ignored	Run `aspect auth status --json`. A signed-in desktop app takes precedence over an environment or stored key.
`auth logout` did not change the account	It only removes the stored CLI key and default workspace. Check the desktop session and `ASPECT_API_KEY`.
You can see a project but cannot download, upload, or organize it	Those actions require their own permissions. Have a workspace or project administrator check your access.

See Authentication and API keys for the complete sign-in order.

Paths

Code	What to do
`invalid_url`	Use `aspect://<workspace>/<project>/<path>`, quote names with spaces, and remove empty path segments.
`no_default_workspace`	Use an explicit workspace in the URL, or set one with `aspect workspace use`.
`not_found`	Use `aspect ls` to check each parent level and confirm the resource is visible to your account.
`ambiguous_name`	Replace the conflicting name with one of the IDs listed in the error.
`not_a_directory`	An intermediate path segment identifies a file. Correct the folder path.
`destination_not_directory`	Upload to a project or an existing directory, not a workspace or file.
`not_mountable`	Mount a project or directory, not an individual asset or workspace.

Mounts and the filesystem service

Run aspect doctor before retrying a failed mount. Install FUSE 3 on Linux or WinFSP on Windows when reported missing. On macOS, follow the mount-helper instructions. See Installation. Commands using --json do not prompt to install Linux or Windows prerequisites. Provision them before automated mount jobs. If daemon_owned_by_desktop appears, restart or quit the signed-in Aspect app to manage its filesystem service. CLI daemon lifecycle commands cannot manage a service owned by that app. For a standalone CLI service, aspect daemon status reports its state. Finish mounted-file work and check for pending uploads before using aspect daemon restart. A service restart can interrupt mounted applications. If a save is not yet visible elsewhere, close its writable file in the application and run aspect daemon status --json. Require writeBackDrained to be true and writeSyncSummary.failureCount to be 0, and resolve mount errors. Failed uploads can leave a drained queue, so check both fields. Missing fields do not confirm completion. See Finish work and unmount.

Uploads and downloads

Symptom	What to do
Files were skipped	Both commands skip name conflicts by default. Use `--replace` for deliberate replacement or `--keep-both` for another copy.
`source_not_found`	Check that the local upload source still exists and is readable.
`destination_not_writable`	Check permissions and space on the local download destination.
`directory_conflict`	A path needed as a directory conflicts with a file, either in the remote upload destination or the local download destination. Choose another destination or resolve that conflict.
`network_timeout` or `network_unreachable`	Restore connectivity and rerun the transfer. Completed files are skipped by default.
A transfer has exit status `1` but still prints JSON	Inspect its `failed` entries or its terminal state/result. Partial failures use structured results too.
`transfer_not_found`	Check the ID and run `aspect transfer list` on the same computer. A newly launched detached job can briefly be absent before it writes its first status.

Starting a job with --detach confirms launch, not successful delivery. Use aspect transfer wait <transfer-id> and inspect its result. A job whose background process stopped may need to be started again; it does not automatically resume after reboot.

Proxies and offline pins

If --variant stream_proxy downloads fewer files than expected, the folder may contain assets without generated proxies. A single missing variant fails; folder downloads leave unmatched assets out. Check processing in Aspect and retry. There is no automatic fallback to originals. See Proxies and previews. For offline access, wait until the required pins show synced in aspect pin list. over_limit requires changing pin selection or storage limits. not_pinned can mean the file is covered by a parent pin instead of having its own. Keep the project mounted before going offline; a new mount command needs API access.

Get help

If the diagnostic message does not resolve the issue, contact the Aspect community with your operating system, aspect --version, the command you ran, and the error code. Redact API keys, signed download URLs, and private filenames before sharing output.

Get started

Work with files

Mounted projects

Reference

Troubleshooting

Installation

Authentication

Paths

Mounts and the filesystem service

Uploads and downloads

Proxies and offline pins

Get help

​Installation

​Authentication

​Paths

​Mounts and the filesystem service

​Uploads and downloads

​Proxies and offline pins

​Get help

Installation

Authentication

Paths

Mounts and the filesystem service

Uploads and downloads

Proxies and offline pins

Get help