Puck docs

Troubleshooting ​

When logs don't show up. Start from what the sender reports, and from the status on the Source's page: "Waiting for logs…" means no Log record has arrived yet, and "Receiving logs" shows when the last one did.

401 or UNAUTHENTICATED: the credential ​

The gateway rejected the credential. Over HTTP (OTLP and Loki push) this is a 401; over gRPC it is UNAUTHENTICATED. Check, in order:

  1. Both variables are set where the sender runs. A Collector or Promtail started by a service manager doesn't see the variables of your shell. Set them in the service's own environment.
  2. The ID and the secret belong together. The ID is the credential's ID from the Source's page, and the secret is the one shown when that credential was issued. The secret can't be shown again: if you don't have it, issue a new credential (see Credentials).
  3. The credential is still active. A revoked credential is rejected. A Source with no active credential is switched off. The Source's page lists the active credentials.
  4. It is new. A credential issued a moment ago works within about a minute.
  5. The secret has no extra characters. A trailing newline or quote from copying breaks it.

A sender that is rejected drops those logs; it doesn't retry. Some senders don't tell you. An OpenTelemetry SDK prints the failure only when debug logging is on (OTEL_LOG_LEVEL=debug for the Node.js SDK) or logs a warning (Python), and the application sees no exception.

429: over the Ingest cap ​

HTTP 429, or RESOURCE_EXHAUSTED over gRPC, means your Team has sent more than its Ingest cap for the UTC day (1 GB on the free tier, counted after decompression). Refused records are not stored. The cap resets at 00:00 UTC. A Collector retries a 429, and a Host Collector's queue on disk holds the records until the reset; an SDK may drop records meanwhile.

The gateway doesn't refuse over the cap yet, so you won't see this today: see Limits. To send less, filter out noisy logs at the sender, or write to us for a higher cap.

TLS and connection problems ​

Puck's ingest is reached at ingest.usepuck.eu, on port 4318 for OTLP over HTTP and Loki push, and port 4317 for OTLP over gRPC. It uses TLS with a certificate from a public authority, so senders need no CA file.

  • Use https://. Ingest speaks TLS only, and never redirects plain HTTP.
  • Use the right port. https://ingest.usepuck.eu:4318 for HTTP. gRPC is ingest.usepuck.eu:4317, and an SDK takes it as a URL: https://ingest.usepuck.eu:4317.
  • Open outbound 4317 and 4318 in the Host's firewall or the network's egress rules.
  • "certificate signed by unknown authority" or "x509" errors mean the sender doesn't trust the certificate. The usual causes are an old or missing system certificate store, a wrong system clock, or a proxy that intercepts TLS. Update the store or fix the clock. Don't turn verification off.
  • A name that doesn't resolve is DNS on the Host. Check that ingest.usepuck.eu resolves from it.

No records yet ​

Everything is connected, there is no error, and Explore is empty.

  • Wait a minute. Senders batch before sending, and Puck takes a moment to store.
  • Did the sender flush? An application with an SDK that exits without shutting it down loses the records it hadn't sent. See OTel SDK.
  • Is the Filter right? Use source:your-slug to see only that Source. Check the time range too.
  • Are the records too old? Records dated more than your Retention plus one day in the past are dropped on arrival. When a Host first connects, only its records from within your Retention arrive. See Limits.
  • Does the Host Collector have access? It needs read access to the files in /var/log and, for containers, to the Docker socket. The Collector's own log says when it can't read something.
  • Is the pipeline wired? If you use your own Collector, the exporter must be in the logs pipeline, and basicauth/obs in service.extensions. See Your OTel Collector.