kataras/iris · error

unexpected file extension: %s

Error message

unexpected file extension: %s

What it means

basicauth.AllowUsersFile loads basic-auth users from a file, and decodeFile dispatches on the file extension to choose JSON or YAML unmarshalling. Any extension other than .json, .yml, .yaml (or no extension) is rejected with this error before any parsing happens.

Source

Thrown at middleware/basicauth/user.go:225

	// We use unmarshal instead of file decoder
	// as we may need to read it more than once (dests, see below).
	var (
		unmarshal func(data []byte, v any) error
		ext       string
	)

	if idx := strings.LastIndexByte(src, '.'); idx > 0 {
		ext = src[idx:]
	}

	switch ext {
	case "", ".json":
		unmarshal = json.Unmarshal
	case ".yml", ".yaml":
		unmarshal = yaml.Unmarshal
	default:
		return fmt.Errorf("unexpected file extension: %s", ext)
	}

	var (
		ok      bool
		lastErr error
	)

	for _, d := range dest {
		if err = unmarshal(data, d); err == nil {
			ok = true
		} else {
			lastErr = err
		}
	}

	if !ok {
		return lastErr
	}

View on GitHub (pinned to 7bedaf55a0)

Solutions

1. Rename the users file to users.json, users.yml, or users.yaml and ensure its content matches that format.
2. If the data is JSON in a differently-named file, copy/rename rather than changing format.
3. Convert other formats (TOML, CSV) to YAML/JSON before passing the path to AllowUsersFile.

Example fix

// before
opts := basicauth.Options{AllowUsersFile: "./users.txt"}

// after
opts := basicauth.Options{AllowUsersFile: "./users.json"}

ext := filepath.Ext(path); switch ext { case "", ".json", ".yml", ".yaml": default: return fmt.Errorf("unsupported: %s", ext) }

func hasSupportedUsersFileExt(path string) bool { e := filepath.Ext(path); return e == "" || e == ".json" || e == ".yml" || e == ".yaml" }

err := opts.Apply(...); if err != nil && strings.HasPrefix(err.Error(), "unexpected file extension") { log.Fatalf("rename users file to .json/.yml/.yaml: %v", err) }

When it happens

Trigger: Calling AllowUsersFile("users.txt"), ("users.toml"), ("auth.conf"), or any path whose filepath.Ext is not .json/.yml/.yaml/.yaml variants or empty.

Common situations: Pointing the option at a .txt, .csv, or .toml file, uppercase extensions like .JSON depending on Ext matching, or generated temp files with random extensions.

Related errors

• empty regex expression
• refresh max age should be bigger than access token's one[%d
• iris: rewrite: unexpected file extension:
• directoryPath is empty
• path is required

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