Most problems fall into a handful of categories, each with a quick, reliable fix. Use the decision tree to find your category, then jump to the matching section below.

​
Diagnose an issue

Before deep debugging, run 100xprompt upgrade. Many issues disappear on the latest release, and it’s the single fastest thing to try.

​
Common issues & fixes

Symptom: 100xprompt: command not found after installing, or the wrong version runs.
1

Reload your shell

The installer updates your shell profile, but an already-open terminal won’t see it until you reload:
exec $SHELL
Or simply open a new terminal window.
2

Confirm it's on your PATH

100xprompt --version
If this prints a version, you’re set. If not, add the install directory (~/.100xprompt/bin) to your PATH - this matters if you installed with --no-modify-path.
3

Reinstall if needed

Re-run the one-line installer to repair a partial install:
curl -fsSL https://100xprompt.com/install | bash
The npm-family package is published as 100xprompt-cli (use that exact name with npm, bun, pnpm, and yarn); Homebrew and Scoop use 100xprompt. Installing the wrong name is a common cause of “command not found.” See Installation.
Symptom: You can’t sign in, or requests fail with an authorization error.
1

Check what's connected

100xprompt auth list
This lists your connected providers and which provider environment variables are currently active.
2

Re-authenticate

Re-run the guided login and pick your provider again:
100xprompt auth login
Authorize in your browser or paste a fresh API key when prompted.
3

Remove and re-add a stale credential

If a provider keeps failing, disconnect it and connect again:
100xprompt auth logout
100xprompt auth login
If you set a provider API key through an environment variable, a typo or an expired key there will override a working login. Confirm the variable is correct, or unset it and rely on auth login. See Authentication.
Symptom: The model you want isn’t in the picker, or selecting it fails.
1

List what you can actually reach

100xprompt models
This is the authoritative list of models you can select right now - your connected providers plus the models 100xprompt ships with.
2

Refresh the catalog

Pull the latest available models on demand:
100xprompt models --refresh
3

Confirm the provider is connected

A model appears only once its provider is connected. Run 100xprompt auth login for that provider, then list models again.
4

Check your provider filters

If you set enabled_providers or disabled_providers in 100xprompt.json, a model can be hidden on purpose. Make sure its provider isn’t excluded.
Model identifiers use the provider/model format and change as new models ship. Always copy the exact string from 100xprompt models rather than typing it from memory. See Models.
Symptom: You’re asked to approve nearly every action and want a smoother flow.Permissions keep you in control, but you can tune how often you’re asked:
  • Approve “always” instead of “once” for actions you trust, so you aren’t asked again for the same kind of thing.
  • Switch permission mode for the session. Use acceptEdits to auto-approve file edits while still confirming commands, or auto to let a trusted session run with fewer interruptions.
  • Use plan mode when you want the opposite - read-only investigation with no changes at all.
  • Set standing rules in 100xprompt.json to allow or deny specific tools and patterns up front.
Match the mode to the task: plan for exploring an unfamiliar codebase, default for everyday work, acceptEdits for a focused refactor you’re supervising. See Permissions.
Symptom: A slash command does nothing, or a tool action is skipped or blocked.
1

Check the name

Confirm the command spelling and that it’s available in your project. A custom command must be defined before you can trigger it - see Commands.
2

Look for a denial

If a tool is being blocked, a permission rule or mode may be denying it. In plan mode, actions that change files or run commands are denied by design - switch modes to proceed. See Permissions.
3

Confirm the tool is allowed for that agent

Each agent has its own set of allowed tools. If the action belongs to a tool the current agent can’t use, switch to an agent that can. See Agents & Subagents.
Symptom: An external tool you registered doesn’t appear, or its actions fail.
1

Recheck the server configuration

Verify the command, URL, and arguments in your MCP configuration. A single wrong path or port stops a server from starting. See Connect Tools & Data with MCP.
2

Verify credentials and environment

Many servers need an API key or token. Confirm the required environment variables are present and valid where 100xprompt runs.
3

Confirm the server runs on its own

Start the server’s underlying command directly in your terminal. If it fails there, fix that first - 100xprompt can connect only to a server that starts cleanly.
4

Restart the session

Servers are picked up when a session starts. After fixing the configuration, start a fresh session so the server is registered.
Once a server connects, its capabilities show up as regular tools automatically. If the tools still don’t appear, the server isn’t connecting - return to step one.
Symptom: 100xprompt web doesn’t open, or the browser can’t reach it.
1

Start the web server

100xprompt web
This starts the server and opens the browser interface.
2

Check the address and port

If the browser can’t connect, the port may be in use. Open the address printed in your terminal directly. See Web.
3

Allow it through your firewall

If you bind to a non-local address to reach it from another device, make sure your firewall permits the connection.
Symptom: 100xprompt doesn’t detect your editor, or the extension isn’t active.
  • Supported editors are Visual Studio Code (and VS Code Insiders), Cursor, and Windsurf. Other editors aren’t integrated.
  • Install the extension from within the app when prompted, then reload your editor window so it activates.
  • Launch from the editor’s terminal so 100xprompt can detect the editor it’s running inside.
Reloading the editor window resolves most “extension not detected” cases. See IDE.

​
Still stuck?

When the category fixes don’t land, run this short escalation loop. Each step either resolves the issue or narrows it.
1

Update to the latest release

100xprompt upgrade
2

Confirm your setup

Re-check the basics: 100xprompt --version, 100xprompt auth list, and 100xprompt models. These three quickly reveal an install, sign-in, or model problem.
3

Isolate the change

If something worked before, ask what changed - a new config value, a moved credential, or an updated provider. Reverting the most recent change often pinpoints the cause.

FAQ

Answers to the questions people ask most often.

Glossary

Definitions for every term used in these fixes.

Permissions

Control what 100xprompt can do and how often it asks.

Authentication

Connect providers and manage credentials.