AdguardTeam/AdGuardHome · error

starting web: %w

Error message

starting web: %w

What it means

Failed to start the web server component during service start. Collected into a joined error alongside any DNS start failure.

Source

Thrown at internal/next/cmd/service.go:71

		pidFilePath: conf.pidFilePath,
	}, nil
}

// type check
var _ service.Interface = (*serviceMgr)(nil)

// Start implements the [service.Interface] interface for *serviceMgr.
func (s *serviceMgr) Start(ctx context.Context) (err error) {
	s.writePID(ctx)

	s.confMgrMu.RLock()
	defer s.confMgrMu.RUnlock()

	var errs []error

	err = s.confMgr.Web().Start(ctx)
	if err != nil {
		errs = append(errs, fmt.Errorf("starting web: %w", err))
	}

	err = s.confMgr.DNS().Start(ctx)
	if err != nil {
		errs = append(errs, fmt.Errorf("starting dnssvc: %w", err))
	}

	return errors.Join(errs...)
}

// writePID writes the PID to the file.  Any errors are reported to log.
func (s *serviceMgr) writePID(ctx context.Context) {
	if s.pidFilePath == "" {
		return
	}

	pid := os.Getpid()
	data := strconv.AppendInt(nil, int64(pid), 10)

View on GitHub (pinned to b41aefbe51)

Solutions

1. Free the port: 'ss -ltnp | grep :3000' and stop the conflicting process
2. Check bind_address/port in config
3. Verify TLS certificate paths and validity if HTTPS is enabled

Example fix

# before
bind_port: 3000  # already in use
# after
bind_port: 3001

func portFree(port int) bool {
	ln, err := net.Listen("tcp", fmt.Sprintf(":%d", port))
	if err != nil { return false }
	_ = ln.Close()
	return true
}

When it happens

Trigger: confMgr.Web().Start(ctx) errors: web bind address already in use, invalid TLS certificate/key, or privileged port without permission.

Common situations: Port 3000/80/443 already occupied by another process, stale PID holding the socket, bad TLS files after certificate renewal.

Related errors

• starting dnssvc: %w
• invalid bind_host value: %s
• starting watcher: %w
• reading cert file: %w
• loading sessions: %w

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