# PromptOwl Troubleshooting Guide

This guide helps you diagnose and resolve common issues in [PromptOwl](https://promptowl.ai). Find your problem below and follow the recommended solutions.

---

## Table of Contents

1. [Quick Diagnostics](#quick-diagnostics)
2. [Authentication Issues](#authentication-issues)
3. [AI Response Problems](#ai-response-problems)
4. [API Key Issues](#api-key-issues)
5. [Tool and MCP Problems](#tool-and-mcp-problems)
6. [Data Room and Artifact Issues](#data-room-and-artifact-issues)
7. [Conversation Problems](#conversation-problems)
8. [Performance Issues](#performance-issues)
9. [Sharing and Permission Errors](#sharing-and-permission-errors)
10. [Enterprise and Team Issues](#enterprise-and-team-issues)
11. [Display and UI Problems](#display-and-ui-problems)
12. [Getting Help](#getting-help)

---

## Quick Diagnostics

### First Steps for Any Issue

Before diving into specific problems, try these universal fixes:

1. **Refresh the page** (Ctrl/Cmd + R)
2. **Hard refresh** (Ctrl/Cmd + Shift + R)
3. **Clear browser cache**
4. **Try a different browser**
5. **Check internet connection**
6. **Log out and log back in**

### Check System Status

| What to Check | How |
|---------------|-----|
| Your connection | Try other websites |
| PromptOwl status | Check status page (if available) |
| LLM provider status | Check OpenAI/Anthropic status pages |
| Browser console | Press F12, check for errors |

---

## Authentication Issues

### Can't Log In

**Symptoms:** Login button doesn't work, error after credentials

**Solutions:**

1. **Check credentials:**
   - Verify email address is correct
   - Check password (case-sensitive)
   - Try password reset if unsure

2. **Email not verified:**
   - Check inbox for verification email
   - Check spam/junk folders
   - Request new verification email

3. **OAuth issues (Google):**
   - Clear Google cookies
   - Try incognito/private mode
   - Ensure pop-ups not blocked

4. **Enterprise access:**
   - Verify you're on correct subdomain
   - Contact admin if access denied
   - Check enterprise is active

### Session Expired

**Symptoms:** Suddenly logged out, actions fail

**Solutions:**
- Log in again (sessions expire after 7 days)
- Check for multiple tabs (one may have logged out)
- Clear cookies and log in fresh

### "User not authenticated" Error

**Symptoms:** Actions fail with authentication error

**Solutions:**
1. Refresh the page
2. Log out and log back in
3. Clear browser cookies for the site
4. Check if session expired

---

## AI Response Problems

### No Response from AI

**Symptoms:** Message sent but no response appears

**Solutions:**

1. **Check API key:**
   - Go to Settings → API Keys
   - Verify key shows "API key Found"
   - Try re-entering the key

2. **Check model selection:**
   - Ensure model is selected on prompt
   - Verify model isn't deprecated
   - Try different model

3. **Network issues:**
   - Check internet connection
   - Try again after a moment
   - Check LLM provider status

### "Rate limit exceeded"

**Symptoms:** Error about too many requests

**Cause:** You've hit the API usage limit

**Solutions:**
- Wait a few minutes and retry
- Check your API usage in provider dashboard
- Consider upgrading API plan
- Spread requests over time

### "Context length exceeded"

**Symptoms:** Error about input being too large

**Cause:** Message or conversation too long for model

**Solutions:**
- Shorten your message
- Start a new conversation
- Switch to model with larger context
- Reduce connected artifact size

### "Content filter" Error

**Symptoms:** Request blocked by content filter

**Cause:** Input flagged by AI provider's safety system

**Solutions:**
- Revise message content
- Remove potentially flagged terms
- Try rephrasing the request
- Contact support if false positive

### "Authentication error with LLM provider"

**Symptoms:** 401/403 error from AI provider

**Cause:** API key invalid or expired

**Solutions:**
1. Go to Settings → API Keys
2. Delete and re-enter your API key
3. Verify key is active in provider dashboard
4. Check key has correct permissions
5. Ensure billing is active with provider

### Response Cut Off

**Symptoms:** AI response stops mid-sentence

**Cause:** Max tokens limit reached

**Solutions:**
- Increase max_tokens in prompt settings
- Ask AI to continue
- Break into smaller requests

### Unexpected or Wrong Responses

**Symptoms:** AI gives irrelevant answers

**Solutions:**
- Review prompt instructions
- Lower temperature for more focused responses
- Add more context to system prompt
- Check if correct model is selected
- Review connected artifacts for relevance

---

## API Key Issues

### "API key not Found"

**Symptoms:** Provider shows no key configured

**Solutions:**
1. Navigate to Settings → API Keys
2. Enter your API key for the provider
3. Click Save
4. Wait for validation
5. Refresh page if still showing not found

### Key Validation Fails

**Symptoms:** Error when saving API key

**Solutions:**
- Verify key copied correctly (no extra spaces)
- Check key format:
  - OpenAI: starts with `sk-`
  - Anthropic: starts with `sk-ant-`
- Verify key is active in provider dashboard
- Check API key has correct permissions
- Ensure billing is set up with provider

### "Invalid API key"

**Symptoms:** Actions fail with invalid key error

**Cause:** Key was revoked, expired, or incorrect

**Solutions:**
1. Generate new key from provider
2. Delete old key in PromptOwl
3. Add new key
4. Verify with test message

---

## Tool and MCP Problems

### Tools Not Appearing

**Symptoms:** Tool selection shows no available tools

**Solutions:**
1. Go to Tools configuration page
2. Check tools are enabled (toggle on)
3. For API tools, verify API key is configured
4. For MCP tools, check server is enabled
5. Refresh the page

### "Tool needs configuration"

**Symptoms:** Tool shows yellow "Needs Config" badge

**Cause:** Required API key not provided

**Solutions:**
1. Expand tool configuration
2. Enter required API key
3. Click Save
4. Status should change to "Ready"

### MCP Server Won't Connect

**Symptoms:** MCP server shows disconnected or errors

**Solutions:**
1. Verify server URL is correct
2. Check server is running
3. Test URL in browser/curl
4. Check firewall isn't blocking
5. Review server logs for errors
6. Try removing and re-adding server

### Tool Returns Errors

**Symptoms:** Tool execution fails

**Solutions by Tool:**

**Calculator:**
- Check expression is valid math
- Avoid special characters

**Search Tools:**
- Verify API key is valid
- Check search quota not exceeded
- Try different search terms

**MCP Tools:**
- Check server is running
- Verify server returned valid response
- Review server logs

### AI Not Using Tools

**Symptoms:** AI ignores available tools

**Solutions:**
- Verify tools connected to prompt
- Ask question that requires tool
- Check tool is appropriate for question
- Review tool description (AI uses this)

---

## Data Room and Artifact Issues

### Artifact Won't Sync

**Symptoms:** Sync status stuck on "Unsynced" or "Modified"

**Solutions:**
1. Open the containing folder
2. Wait for automatic sync
3. Try editing and saving artifact
4. Check artifact has content
5. Verify no special characters causing issues

### AI Not Finding Artifact Content

**Symptoms:** AI says it can't find information that's in artifact

**Solutions:**
1. Check artifact sync status (must be green)
2. Verify artifact is in connected dataset
3. Check dataset is connected to prompt
4. Try different question phrasing
5. Review chunk preview (artifact may be split unexpectedly)

### Link Scraping Failed

**Symptoms:** Link artifact shows no content

**Cause:** Website blocked scraping or requires login

**Solutions:**
- Verify URL is accessible in browser
- Check URL uses http:// or https://
- Some sites block automated access
- Try copying content manually as text artifact

### File Upload Failed

**Symptoms:** Error when uploading file

**Solutions:**
1. Check file size (max 500 MB)
2. Verify supported format:
   - PDF, DOCX, CSV, TXT
3. Ensure file isn't corrupted
4. Try re-saving and uploading
5. Check file isn't password-protected

### Citations Not Appearing

**Symptoms:** AI responses have no source citations

**Solutions:**
1. Verify RAG is enabled on prompt
2. Check artifacts have citation metadata filled
3. Ensure enterprise hasn't disabled citations
4. Confirm artifact is synced
5. Check "Title for Citation" field is populated

---

## Conversation Problems

### Conversation Not Saving

**Symptoms:** Messages disappear after sending

**Solutions:**
1. Check internet connection
2. Refresh page and retry
3. Verify you're logged in
4. Check for error messages in browser console
5. Try different browser

### Can't Find Conversation

**Symptoms:** Conversation disappeared from sidebar

**Solutions:**
1. Check all date groups (Today, Yesterday, etc.)
2. Use search to filter by topic
3. Verify you're in correct prompt
4. Check if shared conversation (look for "Shared by")
5. Conversation may have been deleted

### Memory Not Working

**Symptoms:** AI doesn't use memory context

**Solutions:**
1. Check memory is enabled on prompt
2. Verify you have memories created
3. Ensure memories have content
4. Try toggling memory off and on
5. Memories need relevant keywords to activate

### Conversation History Lost

**Symptoms:** Previous messages not showing

**Cause:** May be viewing different conversation branch

**Solutions:**
- Check conversation selection in sidebar
- Look for branch indicators
- Scroll up in conversation
- Start new conversation if needed

---

## Performance Issues

### Slow Response Times

**Symptoms:** AI takes very long to respond

**Solutions:**
1. Check internet connection speed
2. Try simpler prompt
3. Reduce context/artifact size
4. Switch to faster model (GPT-3.5, Claude Haiku)
5. Check LLM provider status

### Page Loading Slowly

**Symptoms:** PromptOwl pages take long to load

**Solutions:**
1. Clear browser cache
2. Disable browser extensions
3. Try incognito/private mode
4. Check internet connection
5. Try different browser

### Sequential Prompt Hangs

**Symptoms:** Multi-block prompt stops executing

**Cause:** Possible circular reference or timeout

**Solutions:**
1. Check for circular block references
2. Review block configuration
3. Simplify workflow
4. Check individual block outputs
5. Try running blocks separately

---

## Sharing and Permission Errors

### "You do not have access"

**Symptoms:** Can't view shared resource

**Cause:** Permission not granted or revoked

**Solutions:**
1. Contact resource owner
2. Verify correct email was shared with
3. Check team membership
4. Request re-sharing

### Can't Share Resource

**Symptoms:** Share button missing or errors

**Solutions:**
1. Check your role (Owner/Editor can share)
2. Verify enterprise allows sharing
3. Check "showShareButton" isn't disabled
4. Contact admin if feature is restricted

### Shared User Can't Access

**Symptoms:** Person you shared with reports no access

**Solutions:**
1. Verify correct email address
2. Ask them to refresh/log out and in
3. Re-share the resource
4. Check if they need prompt access (for conversations)

### Team Members Not Getting Access

**Symptoms:** Team share doesn't work for some members

**Solutions:**
1. Verify team membership
2. Check member's role in team
3. Ensure team share was saved
4. Have member refresh their view

---

## Enterprise and Team Issues

### Enterprise Settings Not Loading

**Symptoms:** Branding/settings not appearing

**Solutions:**
1. Hard refresh (Ctrl/Cmd + Shift + R)
2. Clear browser cache
3. Verify on correct subdomain
4. Check enterprise is set to Active
5. Contact admin to verify configuration

### Can't Access Enterprise Features

**Symptoms:** Features that should be available aren't

**Solutions:**
1. Check feature toggles in admin panel
2. Verify your role in enterprise
3. Contact enterprise admin
4. Check enterprise subscription status

### Team Settings Not Saving

**Symptoms:** Team changes don't persist

**Solutions:**
1. Verify you're team Owner
2. Check for validation errors
3. Refresh and retry
4. Contact support if persists

---

## Display and UI Problems

### Styling/Theme Issues

**Symptoms:** Wrong colors, broken layout

**Solutions:**
1. Hard refresh page
2. Clear browser cache
3. Try different browser
4. Check if using correct subdomain
5. Disable browser extensions

### "Deprecated Model" Warning

**Symptoms:** Warning blocking prompt execution

**Cause:** Selected model has been deprecated

**Solutions:**
1. Open prompt for editing
2. Change to a supported model
3. Save prompt
4. Warning should clear

### Modal/Dialog Won't Close

**Symptoms:** Popup stuck on screen

**Solutions:**
1. Press Escape key
2. Click outside modal area
3. Refresh page
4. Try different browser

### Content Not Displaying

**Symptoms:** Blank areas where content should be

**Solutions:**
1. Refresh page
2. Check browser console for errors
3. Try different browser
4. Clear cache and cookies
5. Disable ad blockers/extensions

---

## Getting Help

### Before Contacting Support

Gather this information:
- Browser and version
- Steps to reproduce issue
- Error messages (screenshots help)
- When issue started
- What you've already tried

### Support Channels

| Channel | Best For |
|---------|----------|
| Help Center | Documentation, FAQs |
| Email Support | Account issues, bugs |
| Enterprise Admin | Team/enterprise issues |

### Reporting Issues

**Include:**
- Detailed description
- Steps to reproduce
- Expected vs actual behavior
- Screenshots/recordings
- Browser console errors (F12)

### Emergency Contacts

For urgent enterprise issues:
- Contact your PromptOwl administrator
- Email hoot@promptowl.ai
- Reference your enterprise ID

---

## Quick Reference

### Common Error Messages

| Error | Likely Cause | Quick Fix |
|-------|--------------|-----------|
| "User not authenticated" | Session expired | Log in again |
| "Rate limit exceeded" | Too many requests | Wait and retry |
| "Context length exceeded" | Input too large | Shorten message |
| "API key not found" | Key missing | Add in settings |
| "Model deprecated" | Old model | Select new model |
| "No access" | Permission issue | Contact owner |

### Refresh Methods

| Method | What It Does |
|--------|--------------|
| F5 or Ctrl+R | Normal refresh |
| Ctrl+Shift+R | Hard refresh (clears cache) |
| Clear cache | Removes stored data |
| Incognito mode | Fresh session |

### Useful Keyboard Shortcuts

| Shortcut | Action |
|----------|--------|
| F5 | Refresh page |
| F12 | Open developer tools |
| Ctrl/Cmd + Shift + R | Hard refresh |
| Escape | Close modals |

---

## Related Guides

- [Security and Compliance](https://nest.promptowl.ai/d/promptowl-documents/platform/enterprise/security-compliance)
- [API Keys and Model Configuration](https://nest.promptowl.ai/d/promptowl-documents/platform/enterprise/api-keys-model-config)
- [Tool Integration and MCP](https://nest.promptowl.ai/d/promptowl-documents/platform/enterprise/tool-integration-mcp)