AdguardTeam/AdGuardHome · critical

writing config file: %w

Error message

writing config file: %w

What it means

The YAML config was encoded successfully but could not be written to confPath — a filesystem-level failure from maybe.WriteFile (permissions, disk full, missing directory, read-only fs).

Source

Thrown at internal/home/config.go:922

	}

	config.Clients.Persistent = globalContext.clients.forConfig()

	confPath = configFilePath(ctx, l, workDir, confPath)
	l.DebugContext(ctx, "writing config file", "path", confPath)

	buf := &bytes.Buffer{}
	enc := yaml.NewEncoder(buf)
	enc.SetIndent(2)

	err = enc.Encode(config)
	if err != nil {
		return fmt.Errorf("generating config file: %w", err)
	}

	err = maybe.WriteFile(confPath, buf.Bytes(), aghos.DefaultPermFile)
	if err != nil {
		return fmt.Errorf("writing config file: %w", err)
	}

	return nil
}

// validateTLSCipherIDs validates the custom TLS cipher suite IDs.
func validateTLSCipherIDs(cipherIDs []string) (err error) {
	if len(cipherIDs) == 0 {
		return nil
	}

	_, err = aghtls.ParseCiphers(cipherIDs)
	if err != nil {
		return fmt.Errorf("override_tls_ciphers: %w", err)
	}

	return nil
}

View on GitHub (pinned to b41aefbe51)

Solutions

1. Verify write permission on confPath for the service user (chown/chmod)
2. Free disk space; ensure the config directory exists and is writable
3. In containers, mount the config volume read-write
4. Restore disk/FS health if the wrapped error indicates I/O failure

// Preflight writability check
if _, err := os.OpenFile(confPath, os.O_WRONLY, 0o644); err != nil {
    return fmt.Errorf("config not writable: %w", err)
}

// Treat as environmental: alert ops, keep running with current config
if err != nil { alertOps("config write failed: %v", err) }

When it happens

Trigger: Any config persistence operation (setup wizard completion, settings changes via API) when the process lacks write access to the config file path or the disk is full.

Common situations: Running as an unprivileged user, container with read-only config mount, full disk, file locked by another process on some platforms.

Related errors

• writing new config: %w
• networksetup failed to configure dns servers: %w
• reading key file: %w
• reading db: %w
• os.MkdirAll: %s: %w

AI-assisted analysis of AdguardTeam/AdGuardHome@b41aefbe51 (2026-08-27). Data as JSON: /api/errors/834eb3737b3fc87d. Report an issue: GitHub.