XTLS/Xray-core · warning · errors.Error

failed to initialize access logger

Error message

failed to initialize access logger

What it means

Raised by log.Instance.startInternal when initAccessLogger fails: creating the handler for the configured access log (file writer or formatter) returned an error, which is chained. Marked AtWarning because Xray continues running with access logging disabled rather than crashing.

Source

Thrown at app/log/log.go:92

}

// Type implements common.HasType.
func (*Instance) Type() interface{} {
	return (*Instance)(nil)
}

func (g *Instance) startInternal() error {
	g.Lock()
	defer g.Unlock()

	if g.active {
		return nil
	}

	g.active = true

	if err := g.initAccessLogger(); err != nil {
		return errors.New("failed to initialize access logger").Base(err).AtWarning()
	}
	if err := g.initErrorLogger(); err != nil {
		return errors.New("failed to initialize error logger").Base(err).AtWarning()
	}

	return nil
}

// Start implements common.Runnable.Start().
func (g *Instance) Start() error {
	return g.startInternal()
}

// Handle implements log.Handler.
func (g *Instance) Handle(msg log.Message) {
	g.RLock()
	defer g.RUnlock()

View on GitHub (pinned to 7d214f8b09)

Solutions

1. Read the chained Base error to identify the file error (ENOENT vs EACCES)
2. Create the log directory and grant write permission to the xray process user (e.g. mkdir -p /var/log/xray && chown)
3. Point access logs to a path that exists and is writable, or use an empty path to disable access logging

Example fix

// before
"log": { "access": "/var/log/xray/access.log" } // dir missing, EACCES
// after (shell)
// mkdir -p /var/log/xray && chown xray:xray /var/log/xray

// At startup, before instance start, verify the access log path is writable:
if p := cfg.Log.Access; p != "" && p != "none" {
    if err := os.MkdirAll(filepath.Dir(p), 0o755); err != nil { return err }
    if f, err := os.OpenFile(p, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0o644); err != nil {
        return fmt.Errorf("access log not writable: %w", err)
    } else { f.Close() }
}

When it happens

Trigger: Config sets an access log path whose file cannot be created or opened (missing directory, EACCES, name too long), or an access log handler type that fails to initialize.

Common situations: Running as a non-root user with access log pointed at /var/log/xray; log directory not created in Docker images; SELinux denying writes; leftover path pointing to a directory instead of a file.

Related errors

• failed to initialize error logger
• failed to close logger
• failed to start logger
• Log Mask: ipv4 mask must be divisible by 8 and between 0-32
• unable to create log handler for

AI-assisted analysis of XTLS/Xray-core@7d214f8b09 (2026-08-15). Data as JSON: /api/errors/82b93b6c1d5bd607. Report an issue: GitHub.