Troubleshooting

Common issues and how to fix them

General

I’m not receiving notifications

Check 1: Notifications enabled

• Open app → Settings → Notifications
• Toggle should be ON
• Grant system permission when prompted

Check 2: Alert is active

• Go to Alerts
• Toggle switch should be 🟢 (green/on)
• If paused, tap to activate

Check 3: Notifications permission

• iOS: Settings → Dashtray → Allow Notifications
• Android: Settings → Apps → Dashtray → Notifications

Notifications showing but with wrong data

Solution:

1. Go to the alert
2. Check template configuration
3. Verify variable names match your payload
4. Use correct syntax: {{variable_name}}
5. For nested data: {{object.field}}

Can’t see variables in template editor

Why: Webhook hasn’t been received yet

Fix:

1. Send a test event from your service
2. Wait a few seconds
3. Go back to alert
4. Variables should now appear
5. Configure template

---

API & Integration

401 Unauthorized

Cause: Invalid or missing API key

Fix:

1. Generate new API key in Settings → API Keys
2. Include full key in Authorization header:
   Authorization: Bearer sk_test_...
   
3. Don’t add extra spaces or characters
4. Key is case-sensitive

429 Rate Limited

Cause: Too many requests in 60 seconds

Solutions:

• Wait and retry after 60 seconds
• Check Retry-After header for exact time
• Reduce request frequency
• Upgrade to Pro plan:
  • Starter: 100 req/min
  • Pro: 1,000 req/min

400 Bad Request

Usually: Invalid JSON or missing fields

Check:

• title field is present and string
• description field is present and string
• JSON is valid (use JSON validator)
• No extra/unknown fields

Example (correct):

{
  "title": "Build passed",
  "body": "All tests passing"
}

Connection timeout

Cause: Network issue or service down

Fix:

1. Check internet connection
2. Try again in a few seconds
3. Verify correct API endpoint: https://api.dashtray.app

---

Webhooks

Webhook not receiving events

Check 1: URL is correct

• Copy URL from Dashtray (Settings → Alerts)
• Paste exactly into service webhook settings
• No typos or extra characters

Check 2: Service webhook is enabled

• Go to service settings
• Find webhook section
• Make sure it’s activated/enabled
• Check events are selected

Check 3: Trigger the event manually

• If possible, manually trigger in the service
• E.g., manually create a test order in your shop
• This bypasses filters

Check 3: Check service logs

• Most services show webhook delivery logs
• Check if requests are being sent
• Look for error responses

Getting old/cached notifications

Cause: Webhook was triggered before alert was configured

Fix:

1. Test webhook again after configuring template
2. Try from service’s webhook dashboard
3. Trigger a new event in the source system

Webhook URL not working

Cause: Wrong or rotated webhook URL

Fix:

1. Copy the URL fresh from the alert page (don’t type it by hand)
2. Confirm the alert is active — paused alerts reject requests with 429
3. Confirm you’re not exceeding the 60 req/min per-alert limit

---

MCP & Claude

Claude can’t find Dashtray tools

Cause: MCP server not configured

Fix:

1. Get API key from Dashtray
2. Edit ~/.config/Claude/claude_desktop_config.json
3. Add:
   {
     "mcpServers": {
       "dashtray": {
         "command": "npx",
         "args": ["@dashtray/mcp-server"],
         "env": { "DASHTRAY_API_KEY": "sk_test_..." }
       }
     }
   }
   
4. Restart Claude Desktop
5. Try again

MCP notifications not arriving

Check:

1. API key is correct and active
2. Claude has internet connection
3. Notifications enabled in Dashtray app
4. Try sending from REST API to verify API key works

”Tool execution failed”

Usually: API key issue

Fix:

1. Generate new API key
2. Update claude_desktop_config.json
3. Restart Claude
4. Try again

---

Mobile App

App won’t install

Android:

• Check device has Android 8+
• Try restarting device
• Enable “Unknown Sources” if needed

App crashes on startup

Fix:

1. Force close app (Settings → Apps → Dashtray → Force Stop)
2. Clear app cache (Settings → Apps → Dashtray → Storage → Clear Cache)
3. Restart device
4. Reinstall app if needed

Can’t sign in

Check:

1. Internet connection is active
2. Email/password is correct
3. Account exists (try signing up if new)
4. If using Google, check account is accessible

If still failing:

1. Clear app cache
2. Restart device
3. Reinstall app

Settings not saving

Fix:

1. Make sure you tapped “Save” button
2. Wait a few seconds for sync
3. Restart app
4. Try again

---

Account & Billing

Can’t upgrade plan

Check:

1. Internet connection is active
2. Payment method is valid
3. Try different payment method
4. Use same Apple/Google account

Didn’t receive confirmation email

Fix:

1. Check spam/junk folder
2. Wait 5 minutes and check again
3. Request new verification link in app
4. Check email is spelled correctly

Can’t reset password

Fix:

1. Go to login screen
2. Click “Forgot Password”
3. Enter email address
4. Check email for reset link (check spam)
5. Link expires after 30 minutes
6. Create new password

---

Performance

Notifications arriving late

Possible causes:

• High load on Firebase
• Network latency
• Quiet hours enabled
• Alert is paused

Check:

1. Is alert active? (toggle switch)
2. Are quiet hours enabled? (Settings → Quiet Hours)
3. Check notification history for delivery status
4. Try restarting app

App is slow

Fix:

1. Clear app cache (Settings → Apps → Dashtray → Clear Cache)
2. Restart device
3. Update to latest app version
4. Delete old notifications (clear history)

High battery usage

Fix:

1. Reduce notification frequency
2. Check if app is stuck in background (restart)
3. Disable background refresh if not needed
4. Update app to latest version

---

Data & Privacy

Missing notifications in history

Note: Retention varies by plan:

• Starter: 30 days
• Pro: 1 year

Fix:

• Upgrade plan to keep longer history
• Export notifications before they expire

Can’t find a notification

Try:

1. Use search feature (search by title/body)
2. Filter by alert
3. Check date range
4. Scroll up in history

Want to delete all notifications

Warning: Cannot be undone

Steps:

1. Settings → Advanced
2. Clear History
3. Confirm

---

Still Stuck?

Debug Information

When reporting issues, include:

• App version (Settings → About)
• Device type and OS version
• When the issue started
• Steps to reproduce
• Screenshots if helpful

Getting Help

1. Check FAQ - See FAQ
2. Browse docs - Full documentation available
3. Report bug - GitHub Issues
4. Ask question - GitHub Discussions

Emergency Support

For critical issues, email: [e-mail]

---

Common Error Messages

Error	Cause	Fix
”Invalid API Key”	Wrong/expired key	Generate new key in Settings
”Rate Limited”	Too many requests	Wait 60 seconds and retry
”Webhook not found”	Wrong URL or deleted alert	Copy URL again from alert
”No FCM tokens”	Notifications never enabled	Enable in app Settings
”Paused alert”	Alert auto-paused after a flood (500+/min)	Re-enable it from the alert page
”Timeout”	Network issue	Check connection and try again

---

Still having issues? We’re here to help! Reach out on GitHub or email [e-mail].