# Troubleshooting Guide

Solutions to common issues on the platform.

---

## Quick Fixes

Before diving into specific issues, try these first:

1. **Refresh the page** — Solves most display issues
2. **Clear browser cache** — Settings > Privacy > Clear browsing data
3. **Try a different browser** — Chrome, Firefox, Safari, Edge
4. **Check your internet** — Ensure stable connection
5. **Log out and back in** — Resets your session

---

## Account & Login Issues

### Can't Log In

| Symptom | Solution |
|---------|----------|
| "Invalid credentials" | Check email/password spelling; passwords are case-sensitive |
| "Account locked" | Too many failed attempts; wait 15 minutes or reset password |
| "Session expired" | Normal after inactivity; log in again |
| MFA code rejected | Check phone time sync; codes expire in 30 seconds |
| "Account not found" | Verify email address; check spam for verification email |

### MFA Issues

**Lost MFA Device**
1. Click "Can't access your authenticator?"
2. Use backup codes (if you saved them)
3. Contact support with identity verification

**MFA Code Always Wrong**
- Ensure phone time is set to automatic
- Time zones don't matter, but time sync does
- Try waiting for a new code

### Password Reset Not Working

- Check spam/junk folder
- Email may take a few minutes
- Verify you're using the correct email
- Request a new reset link if expired

---

## Broker Connection Issues

### Connection Failed

| Error | Likely Cause | Solution |
|-------|--------------|----------|
| "Invalid credentials" | Wrong API key/secret | Re-copy from broker portal |
| "Permission denied" | Missing API permissions | Enable required permissions in broker |
| "IP blocked" | IP whitelist issue | Add your IP to broker's allowed list |
| "Connection refused" | TWS not running (IBKR) | Start Trader Workstation |
| "Token expired" | Schwab 7-day limit | Re-authorize via OAuth |

### Alpaca Issues

**Paper vs Live Keys**
- Paper keys start with `PK`
- Live keys start with `AK`
- They are NOT interchangeable

**Can't Trade**
- Verify market is open (9:30 AM - 4:00 PM ET)
- Check buying power in Alpaca dashboard
- Ensure account is approved for trading

### Interactive Brokers Issues

**TWS Connection**
- TWS must be running and logged in
- Check API settings: Edit > Global Configuration > API > Settings
- Enable "ActiveX and Socket Clients"
- Default ports: 7496 (live), 7497 (paper)

**"Client ID in use"**
- Close other applications using the same client ID
- Use a unique client ID in settings

### Binance Issues

**IP Restriction Errors**
- Your IP may have changed
- Update IP whitelist in Binance API settings
- Or temporarily disable IP restriction (less secure)

**Futures Not Working**
- Futures requires separate enablement
- Enable futures in Binance account
- Use futures-specific API permissions

### Schwab Re-Authorization

Schwab requires re-authorization every 7 days:
1. You'll see a notification when token expires
2. Go to Settings > Brokers
3. Click "Re-authorize" on Schwab
4. Complete OAuth flow

Set a weekly calendar reminder!

---

## Trading Issues

### Order Rejected

| Reason | Solution |
|--------|----------|
| "Insufficient funds" | Reduce quantity or deposit funds |
| "Market closed" | Trade during market hours |
| "Invalid price" | Limit price too far from market |
| "Symbol not found" | Check ticker spelling |
| "Position limit exceeded" | Reduce position or close others |
| "Day trade limit" | PDT rule applies to accounts < $25k |

### Order Not Filling

**Limit Orders**
- Price may not have reached your limit
- Check order is still active
- Consider widening your limit

**Market Hours**
- Regular hours: 9:30 AM - 4:00 PM ET
- Extended hours require separate enablement
- Some symbols don't trade extended hours

**Low Liquidity**
- Thinly-traded symbols may not fill quickly
- Check bid/ask spread
- Consider smaller order size

### Wrong Position Showing

- Refresh the page
- Check for pending orders
- Verify in your broker's portal
- Corporate actions (splits, dividends) may affect display

### Can't Close Position

1. Check for pending orders on the same position
2. Cancel any pending orders
3. Verify market is open
4. Try placing a new closing order
5. If persistent, close directly in broker portal

---

## Strategy Issues

### Strategy Won't Save

**Syntax Errors**
- Check for missing brackets or quotes
- Verify signal names are spelled correctly
- Use the built-in validator

**Invalid Signals**
- Only whitelisted signals are allowed
- Check [Algorithm Reference](./14-algorithm-reference.md) for valid signals
- Some signals require parameters

### Backtest Failed

| Error | Solution |
|-------|----------|
| "Insufficient data" | Symbol may not have enough history |
| "Invalid date range" | Check start/end dates |
| "Timeout" | Simplify strategy or reduce symbols |
| "No trades generated" | Entry conditions may be too strict |

### Walk-Forward Taking Forever

- Walk-forward tests are compute-intensive
- Complex strategies take longer
- Multi-symbol strategies multiply time
- Check status — it's likely still running

### Can't Graduate to Live

Check each requirement:
- [ ] PSR ≥ 0.95 (statistical quality)
- [ ] Walk-forward ratio ≥ 0.7
- [ ] Broker connected
- [ ] MFA enabled
- [ ] Risk acknowledgement signed

### Paper Trades Not Showing

- Paper trades appear after first simulated fill
- Check if strategy has triggered entry conditions
- Verify paper mode is active
- Refresh the page

---

## Data & Display Issues

### Prices Not Updating

**During Market Hours**
- Check internet connection
- Refresh the page
- Data updates every few seconds

**After Hours**
- After-hours data may be delayed
- Some sources stop updating at market close
- Weekend data is static

### Charts Not Loading

1. Refresh the page
2. Clear browser cache
3. Try a different browser
4. Disable browser extensions
5. Check for JavaScript errors (F12 > Console)

### Missing Historical Data

- Some symbols have limited history
- International symbols may have gaps
- Delisted symbols show partial data
- Crypto data varies by exchange

### Pattern Not Detected

- Pattern detection requires sufficient data
- Some patterns need specific timeframes
- Adjust sensitivity in settings
- Manual patterns may differ from algorithm detection

---

## AI Feature Issues

### AI Analysis Not Working

**Credit Issues**
- Check remaining credits in Settings
- Add more credits or configure BYOK
- Some features require minimum credits

**BYOK Not Working**
- Verify API key is correct
- Check key has required permissions
- Ensure key hasn't been revoked

### Slow AI Responses

- AI analysis can take 30-60 seconds
- Complex requests take longer
- During high load, responses may queue
- Check your internet connection

### "AI Unavailable" Error

- Service may be temporarily down
- Try again in a few minutes
- Check status page for outages
- Contact support if persistent

---

## Notification Issues

### Not Receiving Alerts

**Push Notifications**
1. Check browser notification permissions
2. Verify notifications enabled in Settings
3. Test with a manual alert
4. Some browsers block notifications in incognito

**Email Alerts**
1. Check spam/junk folder
2. Verify email address in Settings
3. Check email notifications are enabled
4. Whitelist our email domain

### Too Many Notifications

1. Go to Settings > Notifications
2. Adjust frequency settings
3. Disable unwanted notification types
4. Review and delete old alerts

---

## Performance Issues

### Platform Running Slowly

1. Close unused browser tabs
2. Clear browser cache
3. Disable browser extensions
4. Try a different browser
5. Check system memory usage

### High CPU/Memory Usage

- Reduce number of open charts
- Close unused watchlists
- Disable auto-refresh if not needed
- Use fewer concurrent data streams

---

## Mobile/Responsive Issues

### Layout Problems on Mobile

- Platform optimized for desktop
- Try landscape orientation
- Use browser's "Request Desktop Site"
- Some features may be limited on mobile

### Touch Issues

- Double-tap to zoom may interfere
- Pinch-zoom can cause display issues
- Try refreshing after orientation change

---

## Export/Import Issues

### Can't Export Data

- Check you have data to export
- Some exports require minimum data
- Try a different date range
- CSV exports work better than JSON for spreadsheets

### Import Failed

| Error | Solution |
|-------|----------|
| "Invalid format" | Check file matches expected format |
| "Too many rows" | Split into smaller files |
| "Invalid symbols" | Remove unrecognized tickers |
| "Date format error" | Use YYYY-MM-DD format |

---

## Security Issues

### Suspicious Activity Alert

If you receive this alert:
1. Change your password immediately
2. Review active sessions in Settings
3. Revoke any unrecognized sessions
4. Enable MFA if not already active
5. Contact support

### Session Revoked Unexpectedly

- Someone may have logged in elsewhere
- Session limit reached (default: 5)
- Admin may have revoked sessions
- Check Settings > Sessions

---

## Getting More Help

### Before Contacting Support

Gather this information:
- What you were trying to do
- What error message appeared (screenshot if possible)
- When the issue started
- Browser and version
- Whether it's reproducible

### Contact Support

- **Email**: support@agencio.cloud
- **Response Time**: Usually within 24 hours
- Include: account email, description, screenshots

### Check Service Status

If many features aren't working, there may be an outage:
- Check the status page
- Follow for updates on social media
- Wait for resolution

---

## Error Message Reference

### Common Error Codes

| Code | Meaning |
|------|---------|
| 400 | Bad request — check your input |
| 401 | Not authenticated — log in again |
| 403 | Not authorized — you don't have permission |
| 404 | Not found — resource doesn't exist |
| 429 | Too many requests — slow down |
| 500 | Server error — try again later |
| 503 | Service unavailable — maintenance or outage |

### Platform-Specific Errors

| Error | Meaning |
|-------|---------|
| "BROKER_PREFLIGHT_FAILED" | Broker connection check failed |
| "GUARDRAIL_BREACH" | Risk limit exceeded |
| "INSUFFICIENT_CREDITS" | Need more AI credits |
| "INVALID_DSL" | Strategy syntax error |
| "OVERFIT_DETECTED" | Walk-forward test failed |

---

## Related Guides

- [Getting Started](./01-getting-started.md) — Initial setup
- [Broker Setup](./17-broker-setup-detailed.md) — Broker configuration
- [Account Settings](./10-account-settings.md) — Account management
- [FAQ](./11-faq.md) — Common questions

---

*If you're still stuck after trying these solutions, contact support with details about what you've tried.*