earshotby raegentGet earshot
Documentation v0.3.2

Start exploring

OverviewStartInstallation and updatingStartAuthentication and onboardingStartFirst runStartTroubleshootingStartWhy Earshot listensCore conceptsScope and editable plansCore conceptsPermissions and trust modesCore conceptsSteering, sessions, rewind, fork, and undoCore conceptsMemory, context, cost, and verificationCore conceptsCLI referenceUsing EarshotProviders and modelsUsing EarshotHeadless outputUsing EarshotEditor integration with ACPUsing EarshotCompatibility guaranteesUsing EarshotMCP serversExtendingIn-process extensionsExtendingSkills and slash commandsExtendingHooks and subagentsExtendingAdding a providerExtendingArchitectureInternals and projectPerformance baselinesInternals and projectRoadmap and current statusInternals and projectRelease and platform QAInternals and project
↑ ↓ navigate · Enter openEsc close
Earshot / Start

Troubleshooting

Diagnose runtime, credentials, shell, model, and provider failures.

Reviewed for 0.3.2 · Latest documentation

Troubleshooting#

Start with:

earshot doctor

It checks the runtime, Git, the shell used for tools, writable state directories, settings JSON, and auth-file permissions without printing credentials.

no credentials for Anthropic: set ANTHROPIC_API_KEY, or run earshot auth login anthropic Exit code 3. Configure credentials for the selected provider. Run earshot auth login <provider> --api-key <key>, set the provider variable, or use interactive onboarding.

unknown model "foo/bar" Exit code 2. Run earshot models to see valid references. A reference is provider/model; a bare model id works when it's unambiguous.

AWS region setting is missing Bedrock reached the AWS SDK, which means credentials resolved fine — you just need AWS_REGION set.

A provider misbehaves in a way not listed here Likely a real bug. Please open an issue with the provider, model and full error.

Windows shell is missing#

Install Git for Windows with Git Bash, reopen the terminal, and run earshot doctor. Headless startup exits 4 when no supported shell is available.

A headless edit did not run#

The default ask mode cannot receive an interactive answer in a headless run. An action requiring approval is refused with an explanation. Choose an explicit permission mode and appropriate rules for your automation; deny rules always apply.

Budget reached#

Headless runs exit 3 when the session cost ceiling is reached. Inspect the budget subtype in JSON output to distinguish this from missing credentials. Use /cost in an interactive session to inspect or adjust the ceiling.

Something unclear?Suggest a correction on GitHub ↗