kataras/iris · error

toml: %w

Error message

toml: %w

What it means

The public iris.TOML() loader panics with 'toml: %w' when filepath.Abs(filename) fails to resolve the absolute path of the TOML configuration file. This is rare and typically only happens with an empty filename or OS-level path resolution errors. Unlike the YAML loader, TOML uses panic instead of returning an error.

Source

Thrown at configuration.go:142

// app.Configure(iris.WithConfiguration(iris.TOML("myconfig.tml"))) or
// app.Run([iris.Runner], iris.WithConfiguration(iris.TOML("myconfig.tml"))).
func TOML(filename string) Configuration {
	c := DefaultConfiguration()

	// check for globe configuration file and use that, otherwise
	// 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

View on GitHub (pinned to 7bedaf55a0)

Solutions

1. Check that the filename argument is a non-empty string before calling iris.TOML.
2. Resolve the absolute path yourself with filepath.Abs first and handle the error to avoid the panic.
3. Recover from the panic with a deferred recover() wrapper if TOML loading is optional.
4. Verify environment variables feeding the filename are set in the deployment environment.

Example fix

// before
c := iris.TOML(cfgFile) // panics if cfgFile is ""
// after
if cfgFile == "" {
    log.Fatal("TOML config path is empty")
}
abs, err := filepath.Abs(cfgFile)
if err != nil {
    log.Fatalf("bad toml path: %v", err)
}
c := iris.TOML(abs)

if filename == "" { return errors.New("toml config path must not be empty") }
if _, err := filepath.Abs(filename); err != nil { return err }

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

When it happens

Trigger: Calling iris.TOML(filename) where filepath.Abs returns an error — most commonly when filename is an empty string, or when working-directory lookups fail in restricted environments. Called from TestConfigurationTOML and production TOML loading.

Common situations: Passing an empty or environment-variable-substituted filename that ends up empty (e.g. TOML_FILE env var not set); running inside a container or chroot where the working directory cannot be resolved.

Related errors

• toml :%w
• iris: switch: empty cases
• default configuration file '<filename>' does not exist
• iris: rewrite: unexpected file extension:
• iris: rewrite: decode:

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