> ## Documentation Index > Fetch the complete documentation index at: https://aspect.inc/docs/llms.txt > Use this file to discover all available pages before exploring further. # Troubleshooting > Resolve authentication, path, mount, transfer, proxy, and offline-pin errors using Aspect's built-in diagnostics. Start with the CLI's version, authentication source, and local diagnostics: ```bash theme={null} 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 --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](/docs/cli/authentication) for the complete sign-in order. ## Paths | Code | What to do | | - | - | | `invalid_url` | Use `aspect:////`, 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](/docs/cli/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](/docs/cli/mounts#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 ` 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](/docs/cli/proxies). 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](https://discord.gg/NGca2AjGvM) 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.