Troubleshooting Guide

Troubleshoot PromptOwl issues - fix authentication, AI responses, API keys, tools, data room, and performance problems.

This guide helps you diagnose and resolve common issues in PromptOwl. Find your problem below and follow the recommended solutions.

---

Table of Contents

1. Quick Diagnostics

2. Authentication Issues

3. AI Response Problems

4. API Key Issues

5. Tool and MCP Problems

6. Data Room and Artifact Issues

7. Conversation Problems

8. Performance Issues

9. Sharing and Permission Errors

10. Enterprise and Team Issues

11. Display and UI Problems

12. 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 [e-mail]

• 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

• API Keys and Model Configuration

• Tool Integration and MCP