# Promptheus Troubleshooting Guide

> This document provides diagnostic procedures and resolution strategies for common issues encountered during Promptheus operation.

- Skill: `tools-only/promptheus-troubleshooting-guide` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add tools-only/promptheus-troubleshooting-guide`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tools-only/promptheus-troubleshooting-guide/raw
- Safety review: pending (external: skill-scanner PASS, skillspector WARNING)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tools-only (https://skillmd.com/u/tools-only)
- Updated: 2026-09-29
- Page: https://skillmd.com/skills/tools-only/promptheus-troubleshooting-guide

---

# Promptheus Troubleshooting Guide

This document provides diagnostic procedures and resolution strategies for common issues encountered during Promptheus operation.

## Provider Configuration Issues

### Provider Auto-Detection Failure

**Symptom:** System fails to detect configured providers

**Resolution:**
```bash
# Explicitly specify provider
promptheus --provider google "Prompt"
promptheus --provider anthropic "Prompt"
promptheus --provider openai "Prompt"
promptheus --provider groq "Prompt"
promptheus --provider qwen "Prompt"
promptheus --provider glm "Prompt"
```

### Incorrect Provider Selection

**Symptom:** System selects unexpected provider

**Diagnostic Steps:**
```bash
# Verify environment configuration
cat .env

# Check environment variables
env | grep -E '(GOOGLE|ANTHROPIC|OPENAI|GROQ|DASHSCOPE|ZHIPUAI|PROMPTHEUS)'

# Override provider selection
export PROMPTHEUS_PROVIDER=google
```

### API Key Validation

**Verification Commands:**
```bash
# Validate specific provider configuration
promptheus validate --providers google
promptheus validate --providers anthropic
promptheus validate --providers openai
promptheus validate --providers groq
promptheus validate --providers qwen
promptheus validate --providers glm

# Test live API connectivity
promptheus validate --test-connection
```

## Installation and Runtime Issues

### Command Not Found Error

**Symptom:** Shell reports `promptheus` command not found

**Resolution:**
```bash
# Reinstall in editable mode
pip install -e .

# Execute via Python module
python -m promptheus.main "Prompt"

# Verify installation
which promptheus
```

### Dependency Resolution Errors

**Symptom:** Import errors or missing module exceptions

**Resolution:**
```bash
# Install required dependencies
pip install -r requirements.txt

# Force reinstallation
pip install -e . --force-reinstall
```

## File Input Issues

### File Not Found Errors

**Symptom:** File input fails with path resolution errors

**Resolution:**
```bash
# Use absolute path
promptheus -f /absolute/path/to/prompt.txt

# Use relative path from current directory
promptheus -f ./relative/path/prompt.txt
```

## Clipboard Integration Issues

### Platform-Specific Requirements

**Linux:**
- Install `xclip` or `xsel`: `sudo apt-get install xclip`

**macOS:**
- Native clipboard support (no additional installation required)

**Windows:**
- Native clipboard support (no additional installation required)

**WSL (Windows Subsystem for Linux):**
- May require X server configuration for clipboard access
- Verify X server is running and DISPLAY variable is set

## Interactive Mode Issues

### Multiline Input Problems

**Symptom:** Unable to insert newlines in prompt input

**Resolution:**
- Use `Shift+Enter` for newline insertion
- Alternative: `Option/Alt+Enter` or `Ctrl+J`
- Fallback: Use plain mode if terminal is unresponsive

### Slash Command Failures

**Common Issues:**
- Commands must begin with `/` prefix (not `:`)
- Use `/help` to display available commands
- Use Tab key for command completion suggestions

### Session Configuration Management

**Commands:**
```bash
# Display current session configuration
/status

# Modify provider
/set provider google

# Modify model
/set model gpt-4o

# Toggle modes
/toggle refine
/toggle skip-questions
```

## Shell Completion Issues

### Completion Script Not Functional

**Symptom:** Tab completion does not work after installation

**Diagnostic Steps:**
```bash
# Verify completion script generation
promptheus completion bash  # Should output script

# Verify promptheus is in PATH
which promptheus

# Reload shell configuration
source ~/.bashrc   # Bash
source ~/.zshrc    # Zsh

# For Poetry environments, create alias
alias promptheus='poetry run promptheus'
```

## Model Discovery Issues

### Model List Not Updating

**Symptom:** Model lists appear outdated or do not include newly available models

**Resolution:**
```bash
# Manually refresh model cache
promptheus validate --test-connection  # This will also refresh cache

# Or, in Web UI:
# Go to Settings and click "Refresh Model Cache" button
```

**Cache Location:**
- On Unix: `~/.promptheus/models_cache.json`
- On Windows: `%APPDATA%/promptheus/models_cache.json`

## Reporting Issues

When reporting issues, include the following information:

1. **Command executed:** Full command with all flags
2. **Error output:** Complete error message and stack trace
3. **Environment details:**
   - Python version (`python --version`)
   - Operating system and version
   - Provider and model in use
   - Installation method (pip, source, Poetry)
4. **Reproduction steps:** Minimal steps to reproduce the issue
5. **Current model cache status:** If issue related to model discovery

**Issue Tracker:** https://github.com/abhichandra21/Promptheus/issues

## MCP Server Issues

### MCP Package Not Installed

**Symptom:** Error message when starting MCP server
```
Error: The 'mcp' package is not installed. Please install it with 'pip install mcp'.
```

**Resolution:**
```bash
# Install MCP package
pip install mcp

# Or install with development dependencies
pip install -e .[dev]

# Verify installation
python -c "import mcp; print('MCP installed successfully')"
```

### MCP Server Connection Issues

**Symptom:** MCP client cannot connect to Promptheus MCP server

**Diagnostic Steps:**
```bash
# Verify MCP server starts correctly
promptheus mcp

# Check for error messages in server output
# Test with direct Python execution
python -m promptheus.mcp_server

# Verify provider configuration
promptheus validate --test-connection
```

**Common Causes:**
- Missing provider API keys
- MCP package not properly installed
- Port conflicts (MCP uses stdio transport)

### MCP Tool Execution Errors

**Symptom:** MCP tools return error responses

**Diagnostic Commands:**
```bash
# Test individual MCP tools
# Use MCP client to call list_providers
# Use MCP client to call validate_environment

# Check provider status
promptheus list-providers

# Validate environment configuration
promptheus validate --providers google,openai
```

**Common Error Types:**
```json
{
  "type": "error",
  "error_type": "ConfigurationError",
  "message": "No provider configured. Please set API keys in environment."
}
```

**Resolution:**
```bash
# Configure provider API keys
promptheus auth google
promptheus auth openai

# Or manually set in .env file
echo "GOOGLE_API_KEY=your_key_here" >> .env
echo "OPENAI_API_KEY=your_key_here" >> .env
```

### AskUserQuestion Integration Issues

**Symptom:** MCP server not handling clarification questions properly

**Understanding the Integration Modes:**

**Interactive Mode** (when AskUserQuestion is available):
- Server automatically asks questions via injected AskUserQuestion function
- Seamless user experience within supported clients

**Structured Mode** (fallback):
- Server returns `clarification_needed` response with formatted questions
- Client responsible for calling AskUserQuestion tool
- Answers mapped back via `answer_mapping` dictionary

**Debugging AskUserQuestion Issues:**
```bash
# Test refine_prompt workflow
# Step 1: Call with basic prompt that should trigger questions
# Step 2: Verify clarification_needed response format
# Step 3: Check questions_for_ask_user_question array format
# Step 4: Verify answer_mapping structure
```

**Expected Response Format:**
```json
{
  "type": "clarification_needed",
  "questions_for_ask_user_question": [
    {
      "question": "Who is your target audience?",
      "header": "Q1",
      "multiSelect": false,
      "options": [
        {"label": "Technical professionals", "description": "Technical professionals"}
      ]
    }
  ],
  "answer_mapping": {
    "q0": "Who is your target audience?"
  }
}
```

### MCP Client Compatibility Issues

**Symptom:** MCP client cannot properly communicate with Promptheus MCP server

**Resolution:**
```bash
# Ensure MCP client supports:
# - Tool calling capabilities
# - JSON response processing
# - AskUserQuestion tool (for interactive mode)

# Test with basic tool calls first
# Verify response format compatibility
# Check error handling consistency
```

### Performance Issues with MCP Server

**Symptom:** Slow response times from MCP tools

**Diagnostic Steps:**
```bash
# Test provider connectivity
promptheus validate --test-connection

# Check for model fallback behavior
# Monitor API response times
# Verify cache utilization (model cache, etc.)
```

**Optimization Tips:**
- Use specific provider/model parameters to avoid auto-detection overhead
- Ensure provider API keys are valid to prevent retry delays
- Consider using cached model information when available

### MCP Server Logging and Debugging

**Enable Debug Logging:**
```bash
# Set logging level for MCP server
export LOG_LEVEL=DEBUG

# Run MCP server with verbose output
promptheus mcp --verbose  # If supported by client
```

**Common Debug Information:**
- Provider initialization sequence
- Tool execution timing
- Question generation process
- Answer mapping validation