vitessio/vitess · error

fail to initialize Table ACL: %v

Error message

fail to initialize Table ACL: %v

What it means

vtaclcheck validates a Table ACL configuration file. It registers the simpleacl factory and calls tableacl.Init with the provided ACL file; if parsing or validating the JSON ACL file fails, the error is wrapped as 'fail to initialize Table ACL: %v' so the user knows their ACL file is invalid before the tool reports it looks good.

Source

Thrown at go/vt/vtaclcheck/vtaclcheck.go:66

	if opts.ACLFile == "" && opts.StaticAuthFile == "" {
		return errors.New("no options specified")
	}

	options = opts

	return nil
}

// Run the check on the given file
func Run() error {
	if options.ACLFile != "" {
		tableacl.Register("simpleacl", &simpleacl.Factory{})
		err := tableacl.Init(
			options.ACLFile,
			func() {},
		)
		if err != nil {
			return fmt.Errorf("fail to initialize Table ACL: %v", err)
		}

		fmt.Printf("JSON ACL file %s looks good\n", options.ACLFile)
	}

	if options.StaticAuthFile != "" {
		mysql.RegisterAuthServerStaticFromParams(options.StaticAuthFile, "", 0)

		fmt.Printf("Static auth file %s looks good\n", options.StaticAuthFile)
	}

	return nil
}

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Read the wrapped error to find the exact JSON/rule problem, then fix the ACL file (validate JSON syntax first with a linter or jq).
2. Ensure every 'factory' name in the ACL file matches a registered implementation (e.g. simpleacl) for the binary being checked.
3. Verify the ACL file path exists and is readable by the process running vtaclcheck.
4. Re-run vtaclcheck; the message 'JSON ACL file %s looks good' confirms the file is valid.

Example fix

// before: malformed rule entry
{"table_rules": [{"table": "t1", "factories": {"simpleacl": {"principals": ["alice"], "groups": "admins"}}}]}
// after: groups must be a list
{"table_rules": [{"table": "t1", "factories": {"simpleacl": {"principals": ["alice"], "groups": ["admins"]}}}]}

data, err := os.ReadFile(options.ACLFile)
if err != nil {
    return fmt.Errorf("ACL file unreadable: %w", err)
}
var cfg map[string]any
if err := json.Unmarshal(data, &cfg); err != nil {
    return fmt.Errorf("ACL file is not valid JSON: %w", err)
}

func isACLInitErr(err error) bool {
    return err != nil && strings.Contains(err.Error(), "fail to initialize Table ACL")
}

if err := vtaclcheck.Run(...); err != nil {
    if isACLInitErr(err) {
        return fmt.Errorf("fix tableacl_config.json (check JSON syntax, factory names, file path): %w", err)
    }
    return err
}

When it happens

Trigger: Running vtaclcheck with options.ACLFile set, when tableacl.Init returns an error: malformed JSON, invalid rule entries (unknown factory names, bad principal/group fields), or an unreadable file path.

Common situations: Hand-edited tableacl_config.json with syntax errors; referencing an ACL factory (like simpleacl) that isn't registered in the target binary; wrong file path/permissions; config produced for a different vitess version with unsupported fields.

Related errors

• malformed spec: doesn't define a range: %q
• conflicting entries: %q overlaps with %q
• failed to update throttler: %v err: %v
• ErrRange
• ErrPartSize

AI-assisted analysis of vitessio/vitess@01a25a7d17 (2026-09-01). Data as JSON: /api/errors/b9c98749e2d55b77. Report an issue: GitHub.