What causes "unable to start observability facilities" in kopia/kopia?

Check the wrapped root cause; if it mentions subdirectory creation, verify the output directory path is writable.

unable to start observability facilities

Error message

unable to start observability facilities

What it means

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.

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).

Example fix

// before
kopia --output-directory /read-only/obs snapshot create /data
// after
mkdir -p /var/cache/kopia/obs
kopia --output-directory /var/cache/kopia/obs snapshot create /data

Defensive patterns

Strategy: validation

Validate before calling

outDir := "/var/cache/kopia/obs"
if err := os.MkdirAll(outDir, 0o700); err != nil {
	log.Fatalf("observability output dir %q not usable: %v", outDir, err)
}

Try / catch

if err := c.start(ctx); err != nil {
	log.Warnf("observability unavailable, continuing without it: %v", err)
	// or fail fast if tracing is mandatory:
	return errors.Wrap(err, "unable to start observability facilities")
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: mkdir permission denied (EACCES): failed to create directory errors explained — this error's family across 32 libraries.

Related errors

AI-assisted analysis of kopia/kopia@82495e54b5 (2026-09-07). Data as JSON: /api/errors/225e4d8a9fc81261. Report an issue: GitHub.

Appendix: source

Thrown at cli/observability_flags.go:127

	command := "unknown"
	if cmd := ctx.SelectedCommand; cmd != nil {
		command = strings.ReplaceAll(cmd.FullCommand(), " ", "-")
	}

	c.outputSubdirectoryName = clock.Now().Format("20060102-150405-") + command

	if (c.saveMetrics || c.pf.saveProfiles || c.pf.profileCPU) && c.outputDirectory == "" {
		return errors.New("writing diagnostics output requires a non-empty directory name (specified with the '--diagnostics-output-directory' flag)")
	}

	return nil
}

// spanName specifies the name of the span at the start of a trace. A tracer is
// started only when spanName is not empty.
func (c *observabilityFlags) run(ctx context.Context, spanName string, f func(context.Context) error) error {
	if err := c.start(ctx); err != nil {
		return errors.Wrap(err, "unable to start observability facilities")
	}

	defer c.stop(ctx)

	if err := c.pf.start(ctx, filepath.Join(c.outputDirectory, c.outputSubdirectoryName)); err != nil {
		return errors.Wrap(err, "failed to start profiling")
	}

	defer c.pf.stop(ctx)

	if spanName != "" {
		tctx, span := tracer.Start(ctx, spanName, oteltrace.WithSpanKind(oteltrace.SpanKindClient))
		ctx = tctx

		defer span.End()
	}

	return f(ctx)

View on GitHub (pinned to 82495e54b5)