{"record":{"id":"e6a3a4daf1c8ec0d","repo":"hasura/graphql-engine","slug":"creating-metadata-file-s-failed-w-e6a3a4","errorCode":null,"errorMessage":"creating metadata file %s failed: %w","messagePattern":"creating metadata file (.+?) failed: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cli/migrate/source/file/file.go","lineNumber":352,"sourceCode":"\t)\n}\n\nfunc (f *File) ReadName(version uint64) (name string) {\n\treturn f.Migrations.ReadName(version)\n}\n\nfunc (f *File) WriteMetadata(files map[string][]byte) error {\n\tvar op errors.Op = \"file.File.WriteMetadata\"\n\n\tfor name, content := range files {\n\t\tfs := afero.NewOsFs()\n\t\tif err := fs.MkdirAll(filepath.Dir(name), os.ModePerm); err != nil {\n\t\t\treturn errors.E(op, err)\n\t\t}\n\n\t\terr := afero.WriteFile(fs, name, content, 0o644)\n\t\tif err != nil {\n\t\t\treturn errors.E(op, fmt.Errorf(\"creating metadata file %s failed: %w\", name, err))\n\t\t}\n\t}\n\n\treturn nil\n}\n","sourceCodeStart":334,"sourceCodeEnd":358,"githubUrl":"https://github.com/hasura/graphql-engine/blob/724551b9ae87845594ef0408cff0e50eb6c90dc5/cli/migrate/source/file/file.go#L334-L358","documentation":"Raised by source/file's WriteMetadata when it cannot write a metadata file under the migrations filesystem (afero.Fs). It wraps the underlying filesystem error with the target path, so the cause is almost always permissions, a read-only FS, or an invalid path.","triggerScenarios":"Calling file driver WriteMetadata (during metadata export or migration operations that persist files) when the migrations directory or its parent is not writable, the afero filesystem is read-only (e.g. embedded/embedfs), or the path doesn't exist and MkdirAll was skipped/failed.","commonSituations":"Running the CLI in a container or CI where /hasura or the project dir is mounted read-only; using an afero MemMapFs or embed FS in tests without write support; file ownership mismatch (running as non-root against a root-owned directory).","solutions":["Check permissions on the migrations directory and its parents; chmod/chown so the running user can write","If using a custom afero.Fs, ensure it supports WriteFile (use OsFs or a writable memfs)","Verify the disk isn't full or the path read-only (mount -o ro)","Run the operation from the project root so relative paths resolve correctly"],"exampleFix":"# before\n$ docker run -v project:/hasura:ro hasura/graphql-engine-cli... # creating metadata file ... failed: permission denied\n\n# after\n$ docker run -v project:/hasura hasura/graphql-engine-cli... # mount writable","handlingStrategy":"validation","validationCode":"// Ensure target is writable before exporting\ninfo, err := fs.Stat(migrationsDir)\nif err == nil && info.IsDir() {\n    probe := filepath.Join(migrationsDir, \".writeprobe\")\n    if err := afero.WriteFile(fs, probe, []byte{}, 0o644); err != nil {\n        return fmt.Errorf(\"migrations dir not writable: %w\", err)\n    }\n    _ = fs.Remove(probe)\n}","typeGuard":null,"tryCatchPattern":"if err := fileDrv.WriteMetadata(...); err != nil {\n    if strings.Contains(err.Error(), \"creating metadata file\") {\n        // filesystem/permission issue: check mount and permissions\n    }\n}","preventionTips":["Mount project directories writable in containers/CI","Prefer afero.OsFs for real writes","Check disk space and ownership before export jobs"],"tags":["filesystem","permissions","afero","metadata","hasura"],"backgroundTag":"file-write-permission-denied","analyzedSha":"724551b9ae87845594ef0408cff0e50eb6c90dc5","analyzedAt":"2026-08-28T07:32:55.105Z","schemaVersion":2},"datasetVersion":"2026-08-28T11:17:15.048Z"}