Troubleshooting

Symptoms, their causes and the fix.

/peekaboot returns 404

Cause: one of these.

The startup log helps to tell these apart. Peekaboot logs a startup summary with the application name, build, server and datasource details whenever it is on, unless you set peekaboot.lifecycle.enabled=false. The summary’s Peekaboot Dashboard line shows the URL, and it is missing where no dashboard is served.

Peekaboot is off in @SpringBootTest

Cause: tests never count as a local run, so Peekaboot stays off in CI. See Configuration, where it turns itself on.

Fix: switch it on for the test that needs it.

@SpringBootTest(properties = "peekaboot.enabled=true")

The Traces tab is empty

Cause: nothing feeds the trace store. Check tracingSpansPossible in GET /peekaboot/api/features.

A Traces tab that is missing altogether means peekaboot.tracing.enabled=false.

Traces arrive late in tests

Cause: spans are exported in batches. The delay is 200 ms while the dev toolbar is on and Spring Boot’s 5 s otherwise, and tests do not turn the toolbar on. A test that reads /peekaboot/api/traces/** right after its request runs before the spans are there. Until they are, /peekaboot/api/traces/{traceId}/insights answers 200 with rootSpan: null.

Fix: shorten the export delay in the test profile, or poll until rootSpan is set.

management:
  opentelemetry:
    tracing:
      export:
        schedule-delay: 50ms

A trace shows a TRUNCATED badge or fewer queries than expected

Cause: the trace hit peekaboot.tracing.max-spans-per-trace (default 500). The oldest spans were dropped, and their queries with them. The badge stays on that trace. Without the badge, the query count is complete.

Fix: raise peekaboot.tracing.max-spans-per-trace. See Configuration, query-heavy application.

A trace has no logs

Cause: one of these.

• The dev toolbar is off. Logs are captured only while peekaboot.dev-toolbar is on.
• The application does not log through Logback. Capture works with Logback only.
• The log line was written on a thread without the trace context. Only lines that carry the trace id are kept. For @Async methods, see the next entry.

Fix: set peekaboot.dev-toolbar: true. See Traces, what gets recorded.

@Async work is missing or shows up as separate traces

Cause: the trace context does not reach the executor thread. Spring Boot does not propagate it by default, and Peekaboot does not switch that on for you.

Fix: enable context propagation.

spring:
  task:
    execution:
      propagate-context: true

Also check that peekaboot.tracing.async and peekaboot.tracing.enabled are not set to false. An application that declares its own Executor bean also needs spring.task.execution.mode=force. See Configuration, peekaboot.tracing and Traces, background work.

The toolbar does not appear

Cause: one of these.

• peekaboot.dev-toolbar is off. It is on only for a local run. Setting peekaboot.enabled=true does not switch it on.
• The response is not HTML with a </body> tag. JSON responses and redirects never get a bar.
• The HTML response is larger than 2 MiB.
• The request matches an injection exclusion: an excluded path prefix, a blocked file extension, an X-Requested-With header or an async dispatch. See Dev toolbar, pages that get the bar.

Fix: set peekaboot.dev-toolbar: true where you want the toolbar outside a local run.

The toolbar says “could not start”

The bar reads:

Peekaboot toolbar could not start — sign in, or check that its script is allowed to load

Cause: the toolbar script was blocked. Either security in front of /peekaboot/** requires a login, or a Content-Security-Policy with a nonce-only script-src refuses the script.

Fix: sign in to the dashboard, or allow /peekaboot/ui/toolbar/toolbar.js in your script-src. See Security, the dev toolbar asks the reader to sign in.

The Meters tab is missing

Cause: there is no MeterRegistry bean. GET /peekaboot/api/features then reports metrics: false. The Insights tab and the stat tiles on Overview are missing too.

Fix: find what excludes Spring Boot Actuator’s metrics auto-configuration and remove it. See The dashboard, which tabs appear.

The Insights tab is missing or a panel says “No data”

See Insights, when the tab appears.

Values show as ******

Cause: Peekaboot masks values whose key or content looks like a secret. The rules can miss a secret or mask a harmless value. See Security, what gets masked, and how.

Fix: set peekaboot.enable-unmasking: true. Then use the “Show secrets” toggle on the Environment and Config tabs, or add ?unmask=true to GET /peekaboot/api/actuator/all/insights. You need both. See Security, two opt-ins before a real value is shown.

The dashboard returns 401

Cause: Peekaboot runs outside a local run, and nothing it can detect protects /peekaboot/**. Its own HTTP Basic guard is then on. It cannot see protection outside Spring Security, such as a VPN, a proxy with basic auth, an IP allowlist or an API gateway.

This also hits smoke tests that start the packaged jar with Testcontainers or docker-compose. That process counts as a deployment, not a test.

Fix: one of these.

• Use the user name and password from the Peekaboot Security block in the startup log.
• Set your own password with peekaboot.security.password.
• Set peekaboot.security.enabled=false where something else already protects the dashboard, or for the smoke-test container.

See Security, securing the dashboard.

Users get a browser login dialog on application pages

Cause: peekaboot.dev-toolbar: true is set in a deployed environment. The toolbar’s requests to /peekaboot/api/** get a 401 with an HTTP Basic challenge, and the browser asks for credentials on whatever page is open.

Fix: remove peekaboot.dev-toolbar: true outside local development. It is off there by default. See Configuration, when Peekaboot is on.

The generated password changes on every restart

Cause: peekaboot.storage.enabled is false, the default outside a local run. The generated password is not saved.

Fix: one of these.

• Set peekaboot.storage.enabled=true to keep the password across restarts.
• Set peekaboot.security.password to your own.
• Set peekaboot.security.credentials-file to a path. Peekaboot writes the credentials there even with storage off.

See Configuration, peekaboot.security.

Peekaboot’s error page does not appear

Cause: one of these.

• peekaboot.error-page.enabled is off. It is on only for a local run.
• The application has its own error page: an error view bean, an error template or a static error/*.html. Or it sets spring.web.error.whitelabel.enabled=false.
• The request does not accept text/html. API clients get the usual JSON error.

Fix: set peekaboot.error-page.enabled: true outside a local run. To show Peekaboot’s page in place of your own, set peekaboot.error-page.override: true, typically in your local profile. The override does not work when the application excludes ErrorMvcAutoConfiguration or maps its own ErrorController to /error. See Configuration, peekaboot.error-page.

Peekaboot’s error page replaces your own

Cause: peekaboot.error-page.override: true is set. Without it, Peekaboot’s page never replaces an error page the application has.

Fix: remove override, or set it only in your local profile. To switch the page off entirely, set peekaboot.error-page.enabled: false.

Stack frames are hidden

Cause: stack-trace folding is on, the default for a local run. Framework frames collapse behind a toggle on the error page and in the Logs tab. Your own frames are never folded.

Fix: click the toggle to expand them. To stop folding, set peekaboot.stack-trace.fold: false. To change which frames fold, set peekaboot.stack-trace.exclude. See Configuration, peekaboot.stack-trace.