Investigate issues

You can investigate an issue by comparing its occurrences and reviewing the available diagnostic context.

Detected failures

Issues detects uncaught exceptions, failed invocations, HTTP 5xx responses returned by the Worker, and console logs written at error level or containing an Error object or stack trace.

Issues detection does not require Workers Logs or tracing. Tracing is only required to add custom application context.

Review issue details

Open the Issues overview, then select an issue.

The issue details page shows when the failure started, how often it occurred, and its current status.

Select an occurrence to review its available diagnostic context:

• The detected error and a stack trace, when available.
• Logs and traces related to the failure.
• The Worker version that produced the occurrence.
• Invocation and request details.
• Application context attached to the active trace span.

The available context depends on the failure type and the telemetry captured for that invocation.

Add application context

Cloudflare automatically captures platform context, but it does not know which application users, accounts, or sessions are relevant. Add these identifiers as early as possible in each invocation so they are attached when an issue occurs.

You can add attributes to the active span with tracing.getActiveSpan() or to a span created with the custom spans API. Turn on tracing before you use either method.

import { tracing } from "cloudflare:workers";

export default {
	async fetch(request) {
		const { userId, accountId, sessionId } = await getAuthDetails(request);
		const span = tracing.getActiveSpan();

		span?.setAttribute("user.id", userId);
		span?.setAttribute("account.id", accountId);
		span?.setAttribute("session.id", sessionId);

		return handleRequest(request);
	},
};

import { tracing } from "cloudflare:workers";

export default {
	async fetch(request: Request): Promise<Response> {
		const { userId, accountId, sessionId } = await getAuthDetails(request);
		const span = tracing.getActiveSpan();

		span?.setAttribute("user.id", userId);
		span?.setAttribute("account.id", accountId);
		span?.setAttribute("session.id", sessionId);

		return handleRequest(request);
	},
} satisfies ExportedHandler;

These attributes appear with related occurrences.

Do not add secrets, access tokens, or sensitive request content to span attributes, logs, or error messages. Handle application identifiers and personal data according to your privacy and data-handling policies.

Issue statuses

Issues do not resolve automatically. Update the status after you investigate or deploy a fix. A delayed occurrence observed before an issue was resolved does not reopen it.

Retention

Occurrence details are available for seven days. Issues remain listed after their occurrences expire. To turn off Issues through Wrangler, set observability.issues.enabled to false and deploy your Worker. Issues stops detecting new failures.