Endpoints troubleshooting

This page covers troubleshooting for Endpoints. For setup, see the installation guide.

Have a question? Ask PostHog AI

Check the Logs tab

The Logs tab on each endpoint's page shows one entry per execution, including both successful and failed runs. Each entry includes metadata like the execution path (inline or materialized), cache outcome, duration, and row count.

Rejected requests that fail validation — such as an invalid refresh value or a missing limit for pagination — also appear as ERROR entries. Filter by log level or search by free text to find specific entries.

Each run returns an execution_id in the API response. This matches the log entry's instance ID, so you can trace a specific API response back to its log. See execution logs for more details.

Endpoint not found (404)

• Verify the endpoint name is correct
• Check that the endpoint is active - inactive endpoints return 404
• Ensure you're using the correct project ID

Authentication errors (401/403)

• Verify your personal API key is correct
• Check that your API key has the endpoint:read scope
• Ensure you're including the Authorization: Bearer <key> header

Version not found

If you get "Version X not found for endpoint":

• Check available versions in the endpoint's UI
• Omit the version parameter to use the latest version

Variable errors

"Variable 'X' is not allowed for this endpoint"

• Check the variables documentation for which variables are supported
• SQL endpoints only accept variables explicitly defined in the query
• Insight endpoints accept the breakdown property name and date_from/date_to (non-materialized only)

"Query references undefined variable(s): X, Y"

• Your query uses {variables.X} placeholder(s) that don't have matching variable definitions
• Define the variable in the data management variables page with a code_name matching the placeholder name
• Ensure the variable is linked to your endpoint

"Variable ID(s) not valid UUIDs"

• Variable IDs must be valid UUID format
• Check that you're using the correct variable ID from data management variables

"Variable ID(s) not found"

• The variable ID(s) don't exist in your project
• Create the variable in data management variables
• Verify you're using the correct project

Rate limiting (429)

"Too many concurrent requests. Please try again later."

• You've hit the concurrency limit
• Reduce parallel requests or wait before retrying

Materialization errors

"Cannot materialize endpoint: ..."

• The endpoint has variables that use unsupported operators or aren't in WHERE clauses. See variables and materialization for supported configurations
• The endpoint is inactive

"Cannot enable materialization on inactive endpoint"

• Activate the endpoint first, then enable materialization

Column type errors

"There's no column... in table. Not all column types are fully supported yet."

• Some column types aren't fully supported yet
• Try simplifying your query or casting columns to supported types

Slow responses

If endpoints are slow:

• Check the Logs tab on the endpoint's page for duration_ms values
• Look at the endpoints usage tab with the filter for the slow endpoint
• Check if the underlying query is optimized
• Consider materializing your endpoint
• Review the query performance in the query log

Further reading

• Endpoints overview - Learn what endpoints are and when to use them
• Getting started - Create your first endpoint
• API reference - Complete API documentation
• API queries - Learn about standard API queries
• SQL documentation - Write SQL queries for your endpoints
• Insights - Create insights to use as endpoints

Solved community questions