Troubleshooting

WhatsApp connection issues

QR code won't scan

• Make sure your phone camera is clean and has good lighting
• Move closer to the screen so the QR code fills the camera frame
• Try using the pairing code instead — it's displayed below the QR code. Enter it in WhatsApp under "Link with phone number"
• Update WhatsApp to the latest version on your phone

QR code expired

QR codes are only valid for a short time. Refresh the page or click the refresh button to generate a new one.

Connection keeps dropping

• Check that your phone has a stable internet connection (Wi-Fi or mobile data)
• WhatsApp requires your phone to be online periodically — if your phone goes offline for too long, the linked device disconnects
• Make sure you haven't exceeded WhatsApp's 4-device limit. Go to WhatsApp → Linked Devices and unlink any devices you're not using
• Update WhatsApp to the latest version

Status stuck on "Connecting"

Wait 30 seconds — connections sometimes take a moment. If it stays stuck:

1. Click the three-dot menu on the instance card
2. Try disconnecting and reconnecting
3. Scan a fresh QR code

AI agent issues

Agent not responding to messages

Check these in order:

1. Is the agent turned on? Go to your instance settings → Auto-Responder Rules → Make sure "Respond to Direct Messages" is enabled
2. Is the sender filtered out? Check your whitelist, blacklist, and contact filter settings
3. Are operating hours active? If you've set operating hours, check that the current time falls within the active window
4. Is the conversation escalated? The agent won't respond to escalated conversations. Check the Escalations page to see if the conversation has been handed to a human
5. Is your AI provider working? If you're using your own provider (BYOC), check that your account is still connected on the AI Providers page. Look for "Expired" or "Revoked" status

Agent giving wrong answers

• Update your Knowledge Base — The agent can only reference documents you've uploaded. If it's giving outdated or incorrect information, update or replace the relevant documents
• Improve your system prompt — Be more specific about what the agent should and shouldn't say. Add explicit instructions for topics where accuracy matters
• Upload more context — If the agent is guessing instead of using your documents, add more relevant content to the Knowledge Base

Agent responding to the wrong people

Review your Auto-Responder Rules:

• Check the whitelist and blacklist
• Review the "Saved Contacts Only" and "New Contacts Only" settings
• Check your group rules to make sure the agent isn't active in unintended groups

Agent responding when it shouldn't

• Check operating hours — Make sure the mode is correct ("Active During" vs. "Active Outside")
• Check group rules — Remove groups where the agent shouldn't be active
• Add numbers to the blacklist — Explicitly block numbers that shouldn't get automated responses

Payment issues

STK push not reaching the customer

• Verify the phone number is in the correct format (e.g., 254... for Kenya)
• The customer's phone must be on and connected to mobile data or Wi-Fi
• Check that the customer has M-Pesa registered on their number
• The customer may have declined a previous prompt — they can only have one active STK push at a time

Payment shows as "Pending" for a long time

• M-Pesa STK pushes expire after about 60 seconds. If the customer doesn't respond in time, the transaction will eventually fail
• Network issues on the customer's end can delay confirmation
• Check the Transactions page for the final status

High failure rate

Common causes:

• Incorrect phone number format
• Customers with insufficient M-Pesa balance
• Customers declining the payment prompt
• Network issues during peak hours

Scheduling issues

Schedule not sending

• Check the task status on the Schedules page — it may be Pending Approval if approval workflow is enabled
• Verify the schedule time hasn't already passed
• Make sure the selected contact groups have members
• Check that the Scheduler toolkit is installed on your instance

Messages sending too slowly

The delay between messages is configurable (5–120 seconds). If messages are going out too slowly, reduce the delay. However, don't set it below 10 seconds — very fast sending can trigger WhatsApp's anti-spam protections.

Kill switch activated accidentally

If you accidentally hit the Kill Switch, go to the Schedules page. Your tasks will be paused. Click the resume button on each task you want to restart.

Browser and sandbox issues

Browser automation failing

• The agent's browser may need to wake up from hibernation (1-3 seconds). If a task fails, try asking the agent to retry.
• Some websites have anti-bot measures that may block automated interaction. The agent uses a stealth browser, but some sites may still resist.
• Login sessions persist, but some websites expire sessions after a period. Ask the agent to re-login if needed.

Code sandbox not executing

• Make sure the Daytona Sandbox toolkit is installed on your instance
• The agent can create sandboxes in Python, TypeScript, and JavaScript. Specify the language if the agent picks the wrong one.
• File exports from sandboxes require the file to exist in the sandbox — if an export fails, the script may not have created the file correctly.

Image generation issues

• Make sure the Fal.ai toolkit is installed on your instance
• Be descriptive in your image requests — the more detail you give, the better the result
• The agent can generate up to 4 images at once. If you need more, ask in batches.

General issues

Dashboard not loading

• Try refreshing the page
• Clear your browser cache
• Try a different browser
• Check your internet connection

Can't sign in

• Try a different sign-in method (Google, GitHub, or passkey)
• Clear browser cookies and try again
• Contact support at support@kasilabs.com

API status shows issues

Check the API Status indicator at the bottom of the dashboard sidebar. If there's a service disruption, wait for it to be resolved.

Getting help

If you can't resolve your issue with the steps above:

• Email support@kasilabs.com with a description of your issue
• Include your instance name and any error messages you're seeing
• Screenshots are helpful