Troubleshooting

Solutions to common issues you may encounter when using Greppilot.

Connection Issues

Database connection fails

If the agent reports a connection error when querying a database:

1. Verify the connection string format — Each database type has a specific format:

   • PostgreSQL: postgresql://user:pass@host:5432/dbname
   • MySQL: mysql://user:pass@host:3306/dbname
   • SQL Server: mssql://user:pass@host:1433/dbname
   • ClickHouse: clickhouse://user:pass@host:8123/dbname

2. Check network access — Ensure the database is reachable from the Greppilot server. Common blockers include firewalls, VPNs, and IP allowlists.

3. Verify credentials — Test the connection string directly with a database client before adding it to Greppilot.

API integration returns authentication errors

For SaaS integrations (Stripe, Linear, PostHog, Langfuse):

1. Check key format — Each service expects a specific prefix:

   • Stripe: sk_live_ or sk_test_
   • Linear: lin_api_
   • PostHog: phx_
   • Langfuse: sk-lf- (secret) and pk-lf- (public)

2. Verify key permissions — Ensure the API key has sufficient scope for the operations you need.

3. Refresh the integration — Ask the agent to refresh the integration, or toggle it off and on in the integrations panel.

Query Issues

Agent generates incorrect SQL

The agent generates SQL based on the database schema it has introspected. If queries are wrong:

1. Refresh the schema — Ask the agent: "Refresh the schema for my database." This re-introspects all tables and columns.

2. Be specific in your request — Include table names, column names, or the kind of aggregation you want. For example, "Show revenue from the orders table grouped by region" is better than "Show revenue by region."

3. Check schema context — Ask the agent: "What tables do you see in my database?" to verify it has the correct schema loaded.

Query returns no data

1. Verify the data exists — Run the query directly against your database to confirm.
2. Check date ranges — If filtering by date, ensure the format matches your database's date columns.
3. Check the integration is enabled — Disabled integrations won't appear in the agent's tool set.

"Tool result truncated" messages

The agent automatically truncates large query results to manage context size. If you're hitting truncation limits, ask the agent to apply filters or aggregations to reduce the result size.

Chart & Dashboard Issues

Chart displays incorrectly

1. Check the data shape — Charts expect specific data formats. For example, a bar chart needs at least one categorical column (x-axis) and one numeric column (y-axis).
2. Update the component — Ask the agent to modify the chart configuration: "Change the x-axis to use the month column."
3. Try a different chart type — Ask the agent to switch to another visualization: "Show this as a table instead."

Components overlap on the dashboard

Ask the agent to reorder the dashboard layout: "Reorganize the dashboard so nothing overlaps." The agent can reposition all components at once.

LLM Provider Issues

"No LLM key configured" error

Greppilot uses a Bring Your Own Key (BYOK) model. You need to provide an API key for an LLM provider:

1. Open the LLM configuration (click the model name in the chat input area, or ask the agent to show it).
2. Enter your API key for one of the supported providers (Anthropic, OpenAI, Google Gemini, DeepSeek, or Ollama).
3. The key is stored locally in your browser and sent securely with each request.

Rate limiting

Chat requests are rate-limited. If you see rate limit errors:

• Wait a moment before retrying.
• Consider using a less frequent polling interval if automating requests.