Troubleshooting

This page covers common issues and how to resolve them. If your problem isn't listed here, open a run on the Jobs page (/jobs) and check its event log and diagnostics for more details.

Agent Not Responding

Symptoms: You send a message in chat or run a workflow, but nothing happens.

Possible causes and solutions:

• Invalid API key. Go to Settings and verify your API key for the provider the agent uses. Try removing and re-entering the key.
• Provider is down. Check the diagnostics on the Jobs page (/jobs). If the provider shows as "Unavailable," the circuit breaker has tripped. Wait for it to recover, or check the provider's status page.
• No API key set. If you're using an agent with a model from a provider you haven't configured, no requests can be sent. Add the key in Settings.

TIP

The diagnostics view on the Jobs page is always your first stop when agents aren't working. It shows you at a glance whether each provider is healthy, degraded, or unavailable.

Connection Failed

Symptoms: A connection shows as "Error" or "Disconnected," or a workflow step fails when trying to use an external tool.

Possible causes and solutions:

• Invalid credentials. Go to Connections, click the affected connection, and verify your credentials. Try disconnecting and reconnecting.
• Service is unreachable. Check if the external service (e.g., PostgreSQL database, Slack workspace) is accessible from your network.
• Permissions changed. If the service requires OAuth, your token may have expired. Disconnect and reconnect to re-authorize.
• Firewall or VPN. Some corporate networks block outbound connections to specific services. Try from a different network to isolate the issue.

Use the Test Connection button on any connection to verify it's working without running a full workflow.

Run Stuck in "Awaiting Approval"

Symptoms: A workflow run shows "Awaiting Approval" and doesn't progress.

Solution: This is expected behavior, not a bug. A step in the workflow has Auto-Approve turned off, which means it needs your manual approval before proceeding.

1. Go to the Jobs page (/jobs).
2. Click the run that's waiting.
3. Find the pending step.
4. Review the details and click Approve or Reject.

WARNING

Runs waiting for approval will stay paused indefinitely. If you have scheduled workflows with approval-required steps, check the Jobs page regularly so runs don't pile up.

If you want the step to proceed without approval in the future, edit the workflow step and turn on Auto-Approve.

High Costs

Symptoms: Your AI provider bills are higher than expected.

Possible causes and solutions:

• Expensive model on routine tasks. Check the Cost & Usage section in Settings to see which runs cost the most. If routine tasks (data gathering, simple summaries) are using Claude or GPT-4o, switch those agents to Gemini 2.5 Flash or GPT-4o mini.
• Long conversation histories. Chat sessions accumulate context over time. Longer histories mean more input tokens per message. Start a new session periodically for routine tasks.
• Overly verbose outputs. If agents are generating very long responses, add a guideline instructing them to be concise, or add word limits to workflow step instructions.
• Frequent scheduled workflows. A workflow running hourly costs 168x more per week than one running daily. Review your schedules in the Workflows section.

See Supported Models for guidance on choosing cost-effective models.

Memory Seems Wrong

Symptoms: An agent references something incorrect, or its behavior doesn't match your expectations based on past interactions.

Possible causes and solutions:

• Incorrect memory entries. Go to Settings → Memory. Review the stored memories. You can edit or delete any entry that's incorrect or outdated.
• Conflicting memories. If the agent received contradictory information across sessions, it may have stored conflicting memories. Delete the incorrect ones.
• Memory not relevant. Some memories activate based on relevance to the current conversation. If a memory is triggering when it shouldn't, review its content and consider whether it's too broad.

INFO

Memory entries are created automatically when the agent learns something significant during a conversation. You always have full control to review, edit, or remove them.

Workflow Produces Unexpected Output

Symptoms: The workflow runs successfully, but the output isn't what you wanted.

Possible causes and solutions:

• Vague instructions. Review the step instructions. Are they specific enough? "Analyze the data" is too vague. "Calculate the week-over-week percentage change for revenue, user count, and churn rate" is much better.
• Missing guidelines. Check whether the right guidelines are assigned to the agent. If the output tone, format, or content doesn't match expectations, a guideline may be missing or not assigned.
• Wrong agent assigned. Verify the workflow is using the agent you intended. Each step can use a different agent if needed.
• Inspect the event log. Open the run on the Jobs page (/jobs) and open the event log. Walk through each action the agent took to find where things went off track.
• Context overload. If the agent has access to too many context files or memories, it may get confused. Simplify the context by removing irrelevant files from the workspace context.

App Won't Start or Crashes

Symptoms: Pencel doesn't open, crashes on launch, or shows a blank window.

Possible causes and solutions:

• Corrupted database. In rare cases, the workspace database can become corrupted. Your data file is a SQLite database in the app's data directory. Try restarting the app first — it runs an integrity check on startup.
• Outdated version. Make sure you're running the latest version of Pencel. The app checks for updates automatically, but you can also download the latest release manually.
• System resources. If your machine is low on memory or disk space, Pencel may struggle. Close other applications and free up disk space.

TIP

If the app crashes repeatedly, check the application logs on your system. On macOS, look in Console.app. On Windows, check Event Viewer. These system-level logs can reveal what's happening before the app interface loads.

Still Stuck?

If none of the above solutions resolve your issue:

1. Check the run's event log for error messages that describe the problem.
2. Check the diagnostics on the Jobs page for provider health issues.
3. Review the event log of any failed run for step-by-step details.
4. Restart Pencel — some transient issues resolve with a fresh start.