hasura/graphql-engine · error

`files` is invalid: %w

Error message

`files` is invalid: %w

What it means

validatePlatform delegates file-operation checking to validateFiles; if any entry of the files[] array in the platform manifest is malformed (invalid from/to paths or unsupported operation), the failure is wrapped as "`files` is invalid". This runs during ValidatePlugin, before any download happens.

Source

Thrown at cli/plugins/util.go:101

	if !isValidSHA256(p.Sha256) {
		return errors.E(
			op,
			fmt.Errorf(
				"`sha256` value %s is not valid, must match pattern %s",
				p.Sha256,
				sha256Pattern,
			),
		)
	}

	if p.Bin == "" {
		return errors.E(op, "`bin` has to be set")
	}

	err := validateFiles(p.Files)
	if err != nil {
		return errors.E(op, fmt.Errorf("`files` is invalid: %w", err))
	}

	return nil
}

func validateFiles(fops []FileOperation) error {
	var op errors.Op = "plugins.validateFiles"

	if fops == nil {
		return nil
	}

	if len(fops) == 0 {
		return errors.E(op, "`files` has to be unspecified or non-empty")
	}

	for _, fop := range fops {
		if fop.From == "" {

View on GitHub (pinned to 724551b9ae)

Solutions

1. Inspect the wrapped error after the colon — it identifies the exact file-entry problem.
2. Fix each files[] entry: valid operation, non-empty relative from/to paths.
3. Re-run ReadPluginFromFile to confirm the manifest validates.

Example fix

// before
"files": [{ "from": "/etc/conf", "to": "conf", "op": "move" }]

// after
"files": [{ "from": "conf", "to": "conf", "op": "copy" }]

for _, f := range pl.Files {
	if f.From == "" || f.To == "" || !knownOps[f.Op] {
		return fmt.Errorf("bad file entry %+v", f)
	}
}

When it happens

Trigger: A files[] entry with an empty from/to path, an operation string not recognized by validateFiles, or path syntax that fails its checks — triggered by ReadPluginFromFile → ValidatePlugin → validatePlatform.

Common situations: Typos in the operation field ("move" vs "rename"), absolute paths where relative ones are required, or copy-pasted file entries pointing at files that don't exist in the new archive layout.

Related errors

• the plugin name %q is not allowed, must match %q
• plugin should be named %q, not %q
• platform (%+v) is badly constructed: %w
• `sha256` value %s is not valid, must match pattern %s
• plugin %q does not offer installation for this platform

AI-assisted analysis of hasura/graphql-engine@724551b9ae (2026-08-28). Data as JSON: /api/errors/60175d62d65869b9. Report an issue: GitHub.