kataras/iris · error

toml :%w

Error message

toml :%w

What it means

iris.TOML() panics with 'toml :%w' when os.ReadFile cannot read the resolved TOML configuration file (file missing, permission denied, or path is a directory). The panic behavior means the application aborts rather than returning a normal error. The wrapped value is the *PathError from os.ReadFile.

Source

Thrown at configuration.go:148

	// return the default configuration if file doesn't exist.
	if filename == globalConfigurationKeyword {
		filename = homeConfigurationFilename(".tml")
		if _, err := os.Stat(filename); os.IsNotExist(err) {
			panic("default configuration file '" + filename + "' does not exist")
		}
	}

	// get the abs
	// which will try to find the 'filename' from current workind dir too.
	tomlAbsPath, err := filepath.Abs(filename)
	if err != nil {
		panic(fmt.Errorf("toml: %w", err))
	}

	// read the raw contents of the file
	data, err := os.ReadFile(tomlAbsPath)
	if err != nil {
		panic(fmt.Errorf("toml :%w", err))
	}

	// put the file's contents as toml to the default configuration(c)
	if _, err := toml.Decode(string(data), &c); err != nil {
		panic(fmt.Errorf("toml :%w", err))
	}
	// Author's notes:
	// The toml's 'usual thing' for key naming is: the_config_key instead of TheConfigKey
	// but I am always prefer to use the specific programming language's syntax
	// and the original configuration name fields for external configuration files
	// so we do 'toml: "TheConfigKeySameAsTheConfigField" instead.
	return c
}

// Configurator is just an interface which accepts the framework instance.
//
// It can be used to register a custom configuration with `Configure` in order
// to modify the framework instance.

View on GitHub (pinned to 7bedaf55a0)

Solutions

1. Verify the file exists at the path: os.Stat(filepath.Abs(filename)) before calling iris.TOML.
2. Use an absolute path for the TOML file in deployments, or resolve relative to a known base directory.
3. Fix file permissions/ownership so the process user can read the file.
4. Wrap the call in a defer/recover if TOML config is optional and you want a fallback to defaults.

Example fix

// before
c := iris.TOML("configuration.tml") // panics if missing
// after
if _, err := os.Stat("configuration.tml"); err != nil {
    log.Println("no toml config, using defaults")
    c := iris.New().Configuration
} else {
    c := iris.TOML("configuration.tml")
}

abs, err := filepath.Abs(filename)
if err != nil { return err }
if info, err := os.Stat(abs); err != nil { return fmt.Errorf("toml config missing: %w", err) } else if info.IsDir() { return errors.New("toml config path is a directory") }

func() (c iris.Configuration) {
    defer func() {
        if r := recover(); r != nil {
            log.Printf("toml read failed: %v", r)
            c = iris.DefaultConfiguration()
        }
    }()
    return iris.TOML(filename)
}()

When it happens

Trigger: Calling iris.TOML(filename) where the file does not exist at the absolute path, lacks read permissions, or is a directory. TestConfigurationTOML exercises this path when the fixture file is absent.

Common situations: Deploying without the configuration.yml/.toml file shipped in the image; running the binary from a different working directory than in development so the relative filename resolves elsewhere; Docker containers running as non-root reading root-owned files.

Related errors

• toml: %w
• default configuration file '<filename>' does not exist
• %w: example: %s
• iris: switch: empty cases
• default configuration file '" + filename + "' does not exist

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