> ## Documentation Index
> Fetch the complete documentation index at: https://dashtray.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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):**

```json theme={null}
{
  "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:
   ```json theme={null}
   {
     "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](/resources/faq)
2. **Browse docs** - Full documentation available
3. **Report bug** - [GitHub Issues](https://github.com/bhupeshpradhan/dashtray/issues)
4. **Ask question** - [GitHub Discussions](https://github.com/bhupeshpradhan/dashtray/discussions)

### Emergency Support

For critical issues, email: [support@dashtray.app](mailto:support@dashtray.app)

***

## 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](https://github.com/bhupeshpradhan/dashtray) or email [support@dashtray.app](mailto:support@dashtray.app).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.