---
title: Troubleshooting
description: Common Mirage setup failures and the fastest path to getting unblocked.
icon: life-ring
---

## Common Issues

### Import Errors After Install (Python)

- Make sure you installed the package into the environment you are actually using.
- If you need resource-specific dependencies, install the matching extra such as `mirage-ai[s3]`, `mirage-ai[redis]`, or `mirage-ai[fuse]`.
- For source installs, run `uv sync --all-extras --no-extra camel` (the `camel` extra conflicts with the `openai` stack, so excluding it keeps the rest installable).

### Import Errors After Install (TypeScript)

- Pick the entrypoint that matches your runtime: `mirage/node` for Node servers and CLIs, `mirage/browser` for browser and edge runtimes, `mirage/core` for runtime-agnostic primitives.
- Native peers like FUSE and Redis are opt-in. Install them only on Node, alongside `mirage`, when you need those resources.
- If your bundler complains about Node built-ins, you are probably importing `mirage/node` from a browser entry. Switch to `mirage/browser` or `mirage/core`.

### Credential Errors

- Check that the resource-specific environment variables are set in the current shell.
- Confirm you followed the right setup guide from the [Setup](/home/setup/s3) section.
- If a resource depends on Google OAuth or bot tokens, verify the scopes and app installation steps.

### FUSE Does Not Mount

- Follow the OS-level setup first: [macOS](/home/setup/macos) or [Linux](/home/setup/linux).
- Then confirm you installed `mirage[fuse]`.
- If Mirage falls back to virtual mode, check the FUSE installation before debugging command behavior.

### Commands Return Empty Output

- Verify the mount prefix and the path you are querying.
- Start with `ls`, `tree`, or `stat` before assuming the resource is broken.
- For remote systems, confirm the underlying account has access to the target resource.

### Docs and Examples Disagree

- Prefer the Python quickstart and the current resource docs over older snippets copied from issues or experiments.
- If something still looks inconsistent, open an issue or contact the team directly.

## Book Time With The Team

If you are blocked and want direct help, book a troubleshooting call:

<Card title="30-Minute Troubleshooting Call" icon="calendar" href="https://cal.com/strukto/30min">
  Book time with the Mirage team on Cal.com.
</Card>
