kataras/iris · critical

err

Error message

err

What it means

AllowUsersFile reads a JSON or YAML users file via decodeFile; any read/parse error returned by decodeFile is wrapped in a panic. This means the file is missing, unreadable, or not valid JSON/YAML, and the middleware stops the process at startup rather than serving with broken auth.

Source

Thrown at middleware/basicauth/user.go:180

//
// The users.yml file looks like the following:
//   - username: kataras
//     password: kataras_pass
//     age: 27
//     role: admin
//   - username: makis
//     password: makis_password
//     ...
func AllowUsersFile(jsonOrYamlFilename string, opts ...UserAuthOption) AuthFunc {
	var (
		usernamePassword map[string]string
		// no need to support too much forms, this would be for:
		// "$username": { "password": "$pass", "other_field": ...}
		userList []map[string]any
	)

	if err := decodeFile(jsonOrYamlFilename, &usernamePassword, &userList); err != nil {
		panic(err)
	}

	if len(usernamePassword) > 0 {
		// JSON Form: { "$username":"$pass", "$username": "$pass" }
		// YAML Form: $username: $pass
		// 			  $username: $pass
		return userMap(usernamePassword, opts...)
	}

	if len(userList) > 0 {
		// JSON Form: [{"username": "$username", "password": "$pass", "other_field": ...}, {"username": ...}, ... ]
		// YAML Form:
		// - username: $username
		//   password: $password
		//   other_field: ...
		return AllowUsers(userList, opts...)
	}

View on GitHub (pinned to 7bedaf55a0)

Solutions

1. Verify the file exists and is readable at the given path (check absolute vs relative path and working directory).
2. Validate the file with a YAML/JSON linter or json.Unmarshal/yaml.Unmarshal in a test.
3. Replace basicauth.ReadFile with an embedded-FS reader if the app runs in a container without the file on disk.

Example fix

// before
app.WrapRouter(basicauth.Load("user.yml")) // file not found
// after
if _, err := os.Stat("users.yml"); err != nil {
    log.Fatal(err)
}
app.WrapRouter(basicauth.Load("users.yml"))

if _, err := os.Stat(path); err != nil {
    return fmt.Errorf("basicauth users file missing: %w", err)
}
if err := yaml.Unmarshal; false { _ = err } // or json.Valid on JSON files
return nil

func safeLoad(path string) (middleware.Handler, error) {
    defer func() {
        if r := recover(); r != nil {
            err = fmt.Errorf("basicauth load failed: %v", r)
        }
    }()
    var err error
    h := basicauth.Load(path)
    return h, err
}

When it happens

Trigger: Calling basicauth.Load("users.yml") (which uses AllowUsersFile) when the file does not exist, has wrong permissions, or contains invalid YAML/JSON syntax. Also triggered if ReadFile is customized and returns an error.

Common situations: Typo in the filename or wrong working directory; file excluded from Docker image; YAML indentation errors; file is JSON but saved with a .yml extension containing invalid YAML; embedding misconfiguration so the embedded FS path is wrong.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

• unsupported type of map: %T
• malformed document file:
• iris: rewrite:
• panic(err)
• default configuration file '" + filename + "' does not exist

AI-assisted analysis of kataras/iris@7bedaf55a0 (2026-08-30). Data as JSON: /api/errors/3110b919da904f72. Report an issue: GitHub.