Skip to main content

Troubleshooting

Common issues and how to fix them.

Agent Issues

Agent won't start

Symptoms

  • •POST /api/agents/{id}/start returns 200 but agent status stays "idle"
  • •No activity entries appear in the log
  • •Dashboard shows agent as idle despite clicking Start

Fix

Check these in order:

  1. API key: Verify your Anthropic key is saved and valid at Dashboard → Settings or call POST /api/keys/validate
  2. Subscription: Ensure your subscription is active via GET /api/billing/check-limits
  3. Backlog: The agent needs at least one queued task to pick up
  4. Vacation mode:Make sure the agent isn't on vacation

Agent stuck on a task

Symptoms

  • •Task has been "in_progress" for a long time
  • •No result or error in the task object
  • •Agent activity log shows no recent entries

Fix

Stop the agent, then manually set the task back to queued:

# Stop the agent
curl -X POST https://api.hivemeld.com/api/agents/my-agent/stop \
  -H "Authorization: Bearer TOKEN"

# Re-queue the stuck task
curl -X PATCH https://api.hivemeld.com/api/backlogs/my-agent/TSK-001 \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "queued"}'

# Restart the agent
curl -X POST https://api.hivemeld.com/api/agents/my-agent/start \
  -H "Authorization: Bearer TOKEN"

If the task keeps getting stuck, the instructions may be too complex. Try breaking it into smaller tasks or simplifying the description.

Agent produces low-quality output

Symptoms

  • •Task results are generic or unhelpful
  • •Agent doesn't follow the role prompt
  • •Output doesn't match what was requested

Fix

Improve the inputs:

  1. Role prompt:Make it specific. Instead of "You are a marketing agent," say "You are a B2B SaaS marketing lead focused on LinkedIn content for CTO personas. Always include a call-to-action and use data-driven claims."
  2. Task descriptions: Be explicit about format, length, audience, and tone
  3. Model choice: Upgrade from Haiku to Sonnet or Opus for tasks requiring nuance

Discord Issues

Bot can't connect to Discord server

Symptoms

  • •OAuth flow completes but no connection appears
  • •POST /api/discord/test returns {"status": "error"}
  • •Messages aren't being posted to channels

Fix

  1. Bot permissions: The bot needs Send Messages, Embed Links, and Read Message History permissions. Re-authorize with the OAuth URL if permissions are missing.
  2. Channel access:The bot must have access to the specific channel. Check Discord server settings → channel permissions.
  3. Token validity:If using the manual connect flow, ensure the bot token hasn't been regenerated in the Discord Developer Portal.

Messages aren't appearing in Discord

Symptoms

  • •API returns {"status": "sent"} but nothing shows in the channel
  • •Some messages appear but others don't

Fix

  1. Check channel mapping: Verify the agent is mapped to the right channel via GET /api/discord/mappings
  2. Message limits: Content is capped at 2,000 characters and embed descriptions at 4,096. Messages exceeding these limits are silently rejected by Discord.
  3. Rate limits:Discord rate-limits bot messages. If you're sending many messages quickly, some may be delayed or dropped.

Billing Issues

Subscription shows as inactive

Symptoms

  • •GET /api/billing/check-limits returns {"active": false}
  • •Agents can't start new tasks
  • •Dashboard shows subscription warning

Fix

  1. Payment method: Check that your card is valid in the billing portal
  2. Webhook processing: If you just subscribed, the Stripe webhook may take a few seconds to process. Refresh and try again.
  3. Stripe status:Log into Stripe and check that the subscription status is "active" (not "past_due" or "canceled")

Usage costs seem too high

Symptoms

  • •Monthly bill is higher than expected
  • •Usage dashboard shows more tasks than anticipated

Fix

  1. Check model usage: Opus tasks cost ~50x more than Haiku. Review per-model costs at GET /api/billing/usage
  2. Agent throttling: Set throttle_seconds on agents to limit how frequently they process tasks
  3. Export report: Download a detailed cost report via GET /api/analytics/export/costs

API Issues

401 Unauthorized on all requests

Symptoms

  • •Every authenticated endpoint returns 401
  • •Token was working before but stopped

Fix

Your token may have been invalidated. Log in again to get a fresh token:

curl -X POST https://api.hivemeld.com/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "you@company.com", "password": "your-password"}'

Make sure you're including the Bearer prefix:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

CORS errors in the browser

Symptoms

  • •Console shows "Access-Control-Allow-Origin" errors
  • •API calls work in curl but fail from the frontend

Fix

The backend allows CORS from localhost:3000 and localhost:3001by default. If you're running the frontend on a different port or domain, set the environment variable:

HIVEMELD_CORS_ORIGINS=localhost:3000,localhost:3001,yourdomain.com

Issue not listed here? Email support@hivemeld.com with your error details and we'll help you debug it.