kataras/iris · error

%w: example: %s

Error message

%w: example:

%s

What it means

auth.Configuration.BindFile wraps the os.ReadFile error with an appended example configuration when the JSON file being bound does not exist (auth/configuration.go:152). The library reads the requested .json file, and on os.ErrNotExist it generates a random sample configuration (MustGenerateConfiguration), marshals it to JSON, and embeds it in the error so the developer can copy a valid file. The underlying cause is a file-not-found error for the given path.

Source

Thrown at auth/configuration.go:152

			},
		},
	}

	return nil
}

// BindFile binds a filename (fullpath) to "c" Configuration.
// The file format is either JSON or YAML and it should be suffixed
// with .json or .yml/.yaml.
func (c *Configuration) BindFile(filename string) error {
	switch filepath.Ext(filename) {
	case ".json":
		contents, err := os.ReadFile(filename)
		if err != nil {
			if errors.Is(err, os.ErrNotExist) {
				generatedConfig := MustGenerateConfiguration()
				if generatedYAML, gErr := generatedConfig.ToJSON(); gErr == nil {
					err = fmt.Errorf("%w: example:\n\n%s", err, generatedYAML)
				}
			}
			return err
		}

		return json.Unmarshal(contents, c)
	default:
		contents, err := os.ReadFile(filename)
		if err != nil {
			if errors.Is(err, os.ErrNotExist) {
				generatedConfig := MustGenerateConfiguration()
				if generatedYAML, gErr := generatedConfig.ToYAML(); gErr == nil {
					err = fmt.Errorf("%w: example:\n\n%s", err, generatedYAML)
				}
			}
			return err
		}

View on GitHub (pinned to 7bedaf55a0)

Solutions

1. Create the missing JSON file at the given path — the error message itself contains a ready-to-use example JSON configuration you can copy (keys contain random values; replace with your own persisted keys).
2. Pass an absolute path or resolve the path from a known base (executable dir / env var) instead of relying on the process working directory.
3. Check the file is included in your deployment (Dockerfile COPY, k8s ConfigMap/volume mount).
4. Alternatively, skip the file and call cfg.BindRandom() to generate keys in memory (note: keys won't persist across restarts).

Example fix

// before
cfg, err := auth.LoadConfiguration("auth.json") // open auth.json: no such file or directory

// after (resolve relative to executable)
exe, _ := os.Executable()
cfg, err := auth.LoadConfiguration(filepath.Join(filepath.Dir(exe), "auth.json"))

func fileReadable(path string) error {
    if filepath.Ext(path) != ".json" {
        return fmt.Errorf("%q is not a .json auth config", path)
    }
    if _, err := os.Stat(path); err != nil {
        return fmt.Errorf("auth config not accessible: %w", err)
    }
    return nil
}
// call before BindFile/LoadConfiguration

var cfg auth.Configuration
if err := cfg.BindFile("auth.json"); err != nil {
    var perr *fs.PathError
    if errors.As(err, &perr) && errors.Is(perr.Err, fs.ErrNotExist) {
        // error text already embeds an example JSON config; log it and/or generate one
        log.Println(err)
        if gerr := cfg.BindRandom(); gerr == nil {
            log.Println("generated random auth configuration in memory")
        }
    } else {
        log.Fatalf("bind auth config: %v", err)
    }
}

When it happens

Trigger: Calling LoadConfiguration/MustLoadConfiguration or Configuration.BindFile with a path ending in .json that does not exist on disk (wrong path, wrong working directory, file not deployed with the app).

Common situations: Relative path resolved from an unexpected working directory (e.g. running tests or a systemd service from a different dir); Docker image built without copying the auth config; typo in filename or extension; config file mounted at a different path in Kubernetes.

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

• iris: rewrite: decode:
• auth: configuration: %s access token is missing from the con
• parse yaml: %w
• toml :%w
• ErrNotFound

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