Skip to main content

​
Python import errors

Run your script in the environment where Mirage is installed. For a uv project, use uv run python your_script.py. Some VFS types need an extra package:
See Python installation for the available extras. If python3 reports that the monty runtime requires the monty extra, or node or js reports that the quickjs runtime requires the quickjs extra, install that extra:
QuickJS also needs a qjs-wasi.wasm module; see QuickJS installation.

​
TypeScript import errors

Use the package for your environment: If a browser build complains about Node built-ins, check for imports from @struktoai/mirage-node. Use the browser package and a browser-supported VFS instead. For missing optional dependencies such as redis or pg, follow TypeScript installation.

​
Credentials or connection errors

  • Set credentials in the environment of the process running Mirage.
  • Check the service URL, account permissions and required token scopes.
  • Follow the setup guide for your VFS.

​
Missing files or empty output

Inspect paths inside Mirage. Replace YOUR_WORKSPACE_ID with your workspace ID:
Use the exact path shown by the listing. Confirm that the connected account can access the file. In SDK code, inspect the command’s exit code and stderr as well as stdout.

​
Writes are refused

Check that the VFS supports the operation and that the mount has write or exec mode. A read-only backend stays read-only even on a writable mount. Session policies can also restrict access.

​
FUSE does not mount

FUSE is optional; ws.shell(...) works without an OS mount. If you need a mounted folder, follow the macOS or Linux setup, then install the binding for your SDK:
  • Python: uv add "mirage-ai[fuse]".
  • TypeScript: follow the FUSE setup, including its native dependency installation steps.

​
Still stuck?

Open an issue with your Mirage version, operating system, SDK, error message and a minimal example. Remove credentials from logs and configuration before sharing them. You can also ask in Discord or book a troubleshooting call.