{"record":{"id":"8cb3cb6eec30fb60","repo":"go-task/task","slug":"task-included-taskfiles-can-t-have-dotenv-declara","errorCode":null,"errorMessage":"task: Included Taskfiles can't have dotenv declarations. Please, move the dotenv declaration to the main Taskfile","messagePattern":"task: Included Taskfiles can't have dotenv declarations\\. Please, move the dotenv declaration to the main Taskfile","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"taskfile/ast/taskfile.go","lineNumber":19,"sourceCode":"package ast\n\nimport (\n\t\"fmt\"\n\t\"time\"\n\n\t\"github.com/Masterminds/semver/v3\"\n\t\"go.yaml.in/yaml/v3\"\n\n\t\"github.com/go-task/task/v3/errors\"\n)\n\n// NamespaceSeparator contains the character that separates namespaces\nconst NamespaceSeparator = \":\"\n\nvar V3 = semver.MustParse(\"3\")\n\n// ErrIncludedTaskfilesCantHaveDotenvs is returned when a included Taskfile contains dotenvs\nvar ErrIncludedTaskfilesCantHaveDotenvs = errors.New(\"task: Included Taskfiles can't have dotenv declarations. Please, move the dotenv declaration to the main Taskfile\")\n\n// Taskfile is the abstract syntax tree for a Taskfile\ntype Taskfile struct {\n\tLocation     string\n\tVersion      *semver.Version\n\tOutput       Output\n\tMethod       string\n\tIncludes     *Includes\n\tSet          []string\n\tShopt        []string\n\tVars         *Vars\n\tEnv          *Vars\n\tTasks        *Tasks\n\tSilent       bool\n\tDotenv       []string\n\tRun          string\n\tInterval     time.Duration\n\tUseGitignore *bool","sourceCodeStart":1,"sourceCodeEnd":37,"githubUrl":"https://github.com/go-task/task/blob/385e5ad92af02877b6d7cf9dcc963b5ed916e70a/taskfile/ast/taskfile.go#L1-L37","documentation":"ErrIncludedTaskfilesCantHaveDotenvs is returned by Taskfile.Merge when an included Taskfile declares a top-level `dotenv:` section. Since dotenv files must be loaded before the main Taskfile is processed, and included Taskfiles are merged after that, dotenv declarations in included files cannot be honored — so Merge rejects them with this error. The dotenv declaration must live in the main (root) Taskfile instead.","triggerScenarios":"A Taskfile referenced via `includes:` contains `dotenv: ['...', ...]` at its top level. The error surfaces during Taskfile parsing/merging, before any task runs, whenever the included file is read.","commonSituations":"Refactoring a monolithic Taskfile into several included files and moving sections (including dotenv) wholesale; sharing a common Taskfile between projects where dotenv was included; copying examples written for older single-file setups. This is a Task v3 layout constraint.","solutions":["Move the `dotenv:` declaration from the included Taskfile into the main (root) Taskfile","Replace dotenv in the included file with explicit `vars:` that the includer can override, or pass env vars in the shell environment","Restructure includes so the file that needs the dotenv values is the main Taskfile, including others only for tasks"],"exampleFix":"# before — included Taskfile\n# common/Taskfile.yml\ndotenv: ['.env']\ntasks:\n  build: ...\n# after — main Taskfile.yml\ndotenv: ['.env']\nincludes:\n  common: ./common\ntasks:\n  build: ...","handlingStrategy":"validation","validationCode":"# Lint included Taskfiles for dotenv before running task:\ngrep -n '^dotenv:' $(find . -name 'Taskfile*.yml' -not -path './Taskfile.yml') && \\\n  echo 'ERROR: dotenv not allowed in included Taskfiles' && exit 1","typeGuard":null,"tryCatchPattern":"if _, err := tf.Merge(); err != nil {\n    if errors.Is(err, taskfile.ErrIncludedTaskfilesCantHaveDotenvs) {\n        return fmt.Errorf(\"move dotenv to the main Taskfile: %w\", err)\n    }\n    return err\n}","preventionTips":["Keep `dotenv:` only in the root/main Taskfile by convention","When splitting a Taskfile into includes, audit each moved section for dotenv/env declarations","Prefer explicit `vars:` over dotenv in shared/included Taskfiles","Add a CI lint step grepping included Taskfiles for a top-level dotenv key"],"tags":["go-task","taskfile","dotenv","includes","configuration"],"backgroundTag":"invalid-taskfile-structure","analyzedSha":"385e5ad92af02877b6d7cf9dcc963b5ed916e70a","analyzedAt":"2026-09-05T09:01:05.226Z","contentChangedAt":"2026-09-05T09:01:05.226Z","schemaVersion":2},"datasetVersion":"2026-09-12T12:17:11.808Z"}