{"record":{"id":"225e4d8a9fc81261","repo":"kopia/kopia","slug":"unable-to-start-observability-facilities","errorCode":null,"errorMessage":"unable to start observability facilities","messagePattern":"unable to start observability facilities","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cli/observability_flags.go","lineNumber":127,"sourceCode":"\tcommand := \"unknown\"\n\tif cmd := ctx.SelectedCommand; cmd != nil {\n\t\tcommand = strings.ReplaceAll(cmd.FullCommand(), \" \", \"-\")\n\t}\n\n\tc.outputSubdirectoryName = clock.Now().Format(\"20060102-150405-\") + command\n\n\tif (c.saveMetrics || c.pf.saveProfiles || c.pf.profileCPU) && c.outputDirectory == \"\" {\n\t\treturn errors.New(\"writing diagnostics output requires a non-empty directory name (specified with the '--diagnostics-output-directory' flag)\")\n\t}\n\n\treturn nil\n}\n\n// spanName specifies the name of the span at the start of a trace. A tracer is\n// started only when spanName is not empty.\nfunc (c *observabilityFlags) run(ctx context.Context, spanName string, f func(context.Context) error) error {\n\tif err := c.start(ctx); err != nil {\n\t\treturn errors.Wrap(err, \"unable to start observability facilities\")\n\t}\n\n\tdefer c.stop(ctx)\n\n\tif err := c.pf.start(ctx, filepath.Join(c.outputDirectory, c.outputSubdirectoryName)); err != nil {\n\t\treturn errors.Wrap(err, \"failed to start profiling\")\n\t}\n\n\tdefer c.pf.stop(ctx)\n\n\tif spanName != \"\" {\n\t\ttctx, span := tracer.Start(ctx, spanName, oteltrace.WithSpanKind(oteltrace.SpanKindClient))\n\t\tctx = tctx\n\n\t\tdefer span.End()\n\t}\n\n\treturn f(ctx)","sourceCodeStart":109,"sourceCodeEnd":145,"githubUrl":"https://github.com/kopia/kopia/blob/82495e54b584c1ef6073c9e1be048f57f8aef078/cli/observability_flags.go#L109-L145","documentation":"This error wraps failures from observabilityFlags.start when initializing observability (metrics/tracing) before running a CLI command. It means kopia could not set up its diagnostics facilities — e.g., it couldn't create output directories or start the metrics listener — and the command aborted rather than run unobserved.","triggerScenarios":"Running any command through runAppWithContext where c.start(ctx) fails: the diagnostics output directory cannot be created (bad --output-dir path or permissions), the metrics listener address is invalid/in use, or tracing setup fails.","commonSituations":"Passing --output-directory pointing to a read-only or nonexistent-parent location; running in a restricted container where /tmp is not writable; configuring a metrics listener on a privileged or occupied port.","solutions":["Check the wrapped root cause; if it mentions subdirectory creation, verify the output directory path is writable.","Create or fix the output directory: 'mkdir -p <dir> && chmod u+w <dir>'.","If a metrics listener address is configured, verify it's valid and not already in use.","Disable observability flags you don't need (omit --output-directory / metrics-listener-address)."],"exampleFix":"// before\nkopia --output-directory /read-only/obs snapshot create /data\n// after\nmkdir -p /var/cache/kopia/obs\nkopia --output-directory /var/cache/kopia/obs snapshot create /data","handlingStrategy":"validation","validationCode":"outDir := \"/var/cache/kopia/obs\"\nif err := os.MkdirAll(outDir, 0o700); err != nil {\n\tlog.Fatalf(\"observability output dir %q not usable: %v\", outDir, err)\n}","typeGuard":null,"tryCatchPattern":"if err := c.start(ctx); err != nil {\n\tlog.Warnf(\"observability unavailable, continuing without it: %v\", err)\n\t// or fail fast if tracing is mandatory:\n\treturn errors.Wrap(err, \"unable to start observability facilities\")\n}","preventionTips":["Point --output-directory at a writable, existing directory.","Pre-create output directories in deployment scripts.","Validate metrics listener addresses (not privileged, not in use).","Drop observability flags when diagnostics are not needed."],"tags":["observability","cli","diagnostics"],"backgroundTag":"mkdir-permission-denied","analyzedSha":"82495e54b584c1ef6073c9e1be048f57f8aef078","analyzedAt":"2026-09-07T20:35:21.689Z","contentChangedAt":"2026-09-07T20:35:21.689Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}