Skip to content
famasi.ai

Troubleshooting

Common issues when installing or using Famasi Agents.

Run doctor first

Before debugging manually, run the diagnostic tool:

Terminal window
npx @famasi/agents@latest doctor

This checks:

  • Which targets are installed
  • Whether provider is linked
  • MCP config presence
  • Skill file existence
  • Waitlist entries

Installation issues

”Command not found” or npx fails

Problem: npx @famasi/agents@latest install doesn’t work.

Fixes:

  • Ensure Node.js 18+ is installed: node --version
  • Clear npx cache: npx clear-npx-cache then retry
  • Try with explicit registry: npx --registry https://registry.npmjs.org @famasi/agents@latest install claude-code

”Unknown install target”

Problem: npx @famasi/agents@latest install <target> says the target is unknown.

Valid targets:

claude-code    codex    generic-mcp    openclaw

chatgpt and claude-ai are hosted surfaces — they don’t have install commands. Use the in-app connector instead.

Install runs but nothing seems to happen

Problem: The install command completes with a JSON output mentioning "mode": "waitlist".

Explanation: The CLI defaults to waitlist mode. Real installers are gated behind the v1 stage.

Fix:

Terminal window
# Enable real installs
FAMASI_AGENTS_STAGE=v1 npx @famasi/agents@latest install claude-code


# Or use the flag
npx @famasi/agents@latest install claude-code --stage v1

Authentication issues

”Authentication failed”

Fixes:

  • Re-run the link command: npx @famasi/agents@latest link provider --provider-id YOUR_PROVIDER_ID
  • Check your API key is correct and not expired
  • Try rotating: ask the agent to “rotate my API key” (uses refreshProviderApiToken)

“No provider linked”

Problem: Agent says it can’t find provider credentials.

Fix:

Terminal window
npx @famasi/agents@latest link provider --provider-id YOUR_PROVIDER_ID

Or set the environment variable:

Terminal window
export FAMASI_PROVIDER_API_KEY=pk_live_...

Full provider authentication details →

OTP not arriving

Fixes:

  • Verify the phone number includes country code (e.g., +234...)
  • Check SMS isn’t blocked by your carrier
  • Wait 60 seconds before requesting a new OTP
  • Try a different phone number if available

Full individual authentication details →

MCP connection issues

”MCP server not responding”

Fixes:

  • Verify .mcp.json exists in your project root
  • Check it points to https://mcp.famasi.ai/mcp
  • Test connectivity: curl -I https://mcp.famasi.ai/mcp
  • Check your network/firewall allows HTTPS to that domain

”No tools available”

Problem: The MCP connection works but no tools appear.

Fixes:

  • Provider tools require authentication — ensure x-api-key is set
  • Check .mcp.json has the headers block with your API key
  • Run npx @famasi/agents@latest doctor to verify config

”Placeholder values present”

Problem: doctor command shows unset config values.

Fix: Run the link command to fill in real credentials:

Terminal window
npx @famasi/agents@latest link provider --provider-id YOUR_PROVIDER_ID

Platform-specific issues

Claude Code: Agent not using Famasi tools

Fixes:

  • Check .claude/agents/famasi-provider.md exists
  • Verify .mcp.json is in the project root
  • Restart Claude Code after installation

Claude Code setup →

Codex: Skill not found

Fixes:

  • Check .famasi/skills/codex/famasi-provider/SKILL.md exists
  • Verify AGENTS.md has the ## Famasi Provider section
  • Run npx @famasi/agents@latest doctor

Codex setup →

OpenClaw: Skill not loading

Fixes:

  • Check .famasi/skills/openclaw/famasi-patient/SKILL.md exists
  • Verify the MCP URL environment variable is set:
    Terminal window
    export FAMASI_MCP_URL=https://mcp.famasi.ai/mcp

OpenClaw setup →

Ordering issues

”No pharmacies found”

Fixes:

  • Medication may not be in stock nearby — try a broader search term
  • Check that location/coordinates are being sent correctly
  • Try searching for the generic name instead of brand name

Widget not loading

Problem: Pharmacy selection or order tracking widget doesn’t appear.

Fixes:

  • Widgets only work in ChatGPT and Claude.ai (hosted surfaces)
  • Terminal clients (Claude Code, Codex) use text-based alternatives
  • Check your browser allows iframes from the Famasi domain

Full widgets reference →

Still stuck?

  1. Run npx @famasi/agents@latest doctor and share the output
  2. Check the CLI reference for all available commands and flags