Docs / Help · Troubleshooting

Troubleshooting

When something's off, it's almost always one of six things: the license, the connection with Cloudflare, a channel that's down, an old version, weak bot replies, or running the command in the wrong folder. This page goes straight to each one — and at the end we tell you where to get human help.

First: Run the Diagnostic

Before guessing, run forjabot doctor. It checks your bot top to bottom and tells you with ✓ / ⚠ / ✗ what's fine and what isn't. It doesn't change anything — it just looks and reports, so it's safe to run as many times as you want.

# general diagnostic — doesn't touch anything, just checks
$ npx forjabot doctor
✓ bot folder detected · business type: barbershop
✓ wrangler.toml · package.json · node_modules
✓ member/config.local.ts
✓ valid license · plan pro
⚠ there's a new version (1.2.0 → 1.4.0)
✓ the bot responds online
1 warning · everything else is fine

Here's what it checks, and what it means when something shows up with ⚠ or ✗:

Common Problems

1 · "Invalid or expired license"

Your license controls whether you can install and update bots from the catalog — it doesn't control the bot that's already running. Your bot lives in your own Cloudflare account, so even if the license expires, the bot does NOT shut down: it keeps serving your customers normally. The only thing that gets blocked is downloading new templates or pulling updates.

To fix it: revalidate by running forjabot doctor again, check that the key is saved in ~/.forja/config.json, or pass it directly again with --key.

# revalidate by passing your license directly
$ npx forjabot doctor --key HZN-XXXX-XXXX-XXXX
✓ valid license · plan pro

2 · "wrangler not connected" / Cloudflare auth error

Cloudflare is the cloud where your bot lives, and wrangler is the tool that deploys there. If you see an authentication or session error when publishing, it's almost always that your Cloudflare session expired. It's fixed by reconnecting the account — it opens your browser so you can authorize it.

# reconnect your Cloudflare account (opens the browser)
$ pnpm wrangler login
✓ signed in successfully

When you're done, deploy again with pnpm deploy (or ask your agent to publish the bot).

3 · The Bot Isn't Responding on a Channel

If the bot works on Telegram but not on WhatsApp, or the other way around, it's almost never a problem with the bot itself — it's the connection for that channel. Check in this order:

1. The connections panel

   Open /admin/conexiones in your panel. Each channel has a badge: green = connected, gray = not connected. If it's gray, that's the culprit.

2. The channel's secrets

   Each channel needs its own keys (Telegram token, Twilio credentials for WhatsApp, etc.). If they're missing or wrong, the channel won't receive messages. They're saved as secrets, never in the chat.

3. WhatsApp's 24-hour window

   WhatsApp only lets you reply freely to someone who messaged you in the last ~24h. Outside that window you need an approved template. If it "only sometimes doesn't reply" on WhatsApp, this is usually why — not a bug.

4 · "I Have an Old Version"

If doctor tells you there's a newer version, you pull the improvements and fixes with forjabot update. It updates the template's code while keeping your configuration untouched: your member/config.local.ts, your knowledge base, and your keys aren't touched.

$ npx forjabot update
↗ new version: 1.2.0 → 1.4.0
✓ updated · your configuration stayed intact
# to publish the change: reinstall and deploy
$ pnpm install && pnpm deploy

Updating doesn't publish on its own: the change stays in your folder until you reinstall dependencies and deploy. Your agent can do both steps for you.

5 · The Bot Answers Poorly or Is Missing Information

If it replies with stale data, makes things up, or sounds off-tone, it's not a technical error: it just needs context or a tune-up. You don't open the terminal for this — you ask your agent in plain language and it edits the knowledge base, the tone, or the bot's instructions.

Examples of what you can tell it: "the bot doesn't know our new hours, tune it up," "it was curt with a customer, adjust its tone," or "give it maintenance before the end of the month." Remember that behavior changes also aren't live until the bot is deployed.

6 · "I Can't Find My Bot"

The update and doctor commands look for your bot via a marker (.horizontes-bot.json) in the current folder and its subfolders. If you run it from somewhere else, it won't find it. The fix: go into the bot's folder before running the command, or pass it the path directly.

# option A — go into the bot's folder and run the command there
$ cd ~/mis-bots/barberia
$ npx forjabot doctor
# option B — pass the path directly
$ npx forjabot doctor ~/mis-bots/barberia