Wrong template names, mismatched input/output paths, and bad parser keys are the usual reasons swiftgen.yml fails. Here is how to read the errors and fix each one correctly.
When swiftgen.yml is misconfigured, SwiftGen fails fast and prints a message describing what it could not do — an unknown template, an input path it could not find, an unrecognized key, or a YAML it could not parse. The single most useful habit when fixing config errors is to run SwiftGen directly from the terminal with swiftgen config run rather than through an Xcode build phase, because the terminal shows the full error text while a build phase can bury or truncate it. SwiftGen also offers a config lint command that validates the structure of your configuration without generating, which is handy for catching mistakes early. Read the error literally: it usually names the parser, the key, or the path involved. Config errors fall into a few recurring categories — YAML structure, template names, input/output paths, and parser-specific keys — and each has a direct fix. The sections below walk through them roughly in order of how often they trip people up, so you can match your error text to a cause and correct it without trial and error. Because SwiftGen stops at the first blocking problem, fixing one error at a time and rerunning is far more effective than trying to correct several suspected issues at once and losing track of which change actually mattered.
Because swiftgen.yml is YAML, it is whitespace-sensitive, and the most basic failures come from indentation and structure rather than SwiftGen concepts. YAML requires spaces, never tabs, and every nesting level must align consistently. A parser block like xcassets must contain its inputs and outputs at the correct depth; if outputs is indented wrong, SwiftGen may not associate it with the parser and will complain about a missing template or output. A single misaligned key can make the whole file fail to parse with a generic YAML error that does not obviously point at the offending line. When you see a parse error, check that you used spaces throughout, that sibling keys share the same indentation, and that lists use consistent dash indentation. Editors configured to insert tabs are a frequent hidden cause, so enable visible whitespace or configure the editor to use spaces for YAML. Validating the file with a YAML linter, separate from SwiftGen, quickly isolates pure structural problems from SwiftGen-specific ones. Fixing the structure first is worthwhile because a malformed file prevents SwiftGen from reaching the more specific checks. If your editor supports an EditorConfig file, adding one that forces spaces for .yml files removes this entire class of error for everyone on the project rather than relying on each contributor to configure their editor correctly.
Each output must specify which template to use, either a built-in one via templateName or a custom file via templatePath. A very common error is a templateName that does not exist — a typo, an outdated name, or a name from a different parser. SwiftGen validates the template name against the built-in templates available for that specific parser, and the built-in set differs per parser, so a name valid for strings may not exist for xcassets. When SwiftGen reports it cannot find the named template, check the exact spelling and confirm the name is one the current SwiftGen version provides for that parser; the documentation lists the built-in templates per parser. Do not mix templateName and templatePath for the same output — use one. If you intend a custom template, make sure templatePath points at an existing Stencil file resolved relative to the config. Template names have occasionally changed across major SwiftGen versions, so a config that worked on an older version may reference a name that no longer exists after an upgrade. Aligning the template name with the parser and the installed version resolves these errors directly. If you are unsure which templates your installed version provides, SwiftGen can list the available built-in templates per parser from the command line, which is the most reliable way to confirm a name rather than guessing from memory or an old blog post.
SwiftGen must be able to find every input it is told to parse, and a wrong inputs path is one of the most frequent failures. Paths are resolved relative to the configuration file, or relative to a top-level input_dir if you set one, so a path that looks right in isolation can still miss because of where the config lives. When SwiftGen reports it cannot find an input, verify the path from the config's own directory, checking for the usual culprits: a wrong folder name, a missing subdirectory, a file that was moved, or a case mismatch that matters on case-sensitive systems. For parsers like xcassets the input should point at the .xcassets bundle; for strings it points at the .strings or .stringsdict files or their containing directory, depending on how you structure it. If you use input_dir, remember individual inputs are then relative to that base, so do not repeat the base in each path. Listing multiple inputs is allowed and SwiftGen merges them, but every listed path must exist. Correcting inputs so each resolves to a real, existing resource is the fix. A quick way to confirm a path is to change into the config's own directory in the terminal and list the path there; if the shell cannot find it from that location, neither can SwiftGen.
The outputs block tells SwiftGen where to write generated code, and mistakes here either fail generation or write files somewhere useless. The output path is resolved relative to the config or to a top-level output_dir. A common error is pointing the output at a directory that does not exist — SwiftGen may not create missing intermediate directories, so generation fails until you create the folder or fix the path. Another is writing to a location that is not part of your Xcode target, which does not error but leaves the compiler unable to see the symbols. Confirm the output file path matches exactly the file included in your target's Compile Sources. If you set output_dir, individual output paths are relative to it, so avoid duplicating the base. When multiple parsers write to the same file, ensure that is intentional, because a later output can overwrite an earlier one. Verifying that each output resolves to an intended, existing directory and to a file your target actually compiles ensures the generated code both writes successfully and becomes available to your code. If you want several parsers to contribute to one file deliberately, SwiftGen supports listing multiple outputs, so prefer explicit separate output files per parser unless you have a specific reason to combine them and have confirmed the template supports it.
Each parser recognizes a specific set of keys, and using a key that belongs to a different parser or misspelling an option produces an error or is silently ignored. The top-level keys under a parser are typically inputs, filter, outputs, and options, with template selection and params living inside outputs. A frequent mistake is placing templateName or params at the parser level instead of inside outputs, or using a parser name that does not exist — SwiftGen supports a defined set of parsers such as xcassets, strings, fonts, ib, json, yaml, plist, and coredata, and inventing a name outside that set fails. Options are parser-specific too, so an option valid for one parser may be unrecognized by another. When you get an unexpected-key or unknown-parser error, compare your keys against the documentation for that exact parser and version, and move any misplaced keys to their correct nesting level. Because SwiftGen validates structure per parser, matching your keys to the documented schema for the parser you are configuring eliminates this category of error and is why keeping the official parser documentation open while editing the config pays off. When a valid-looking option seems to have no effect, suspect that it belongs to a different parser or that it lives at the wrong nesting level, since SwiftGen ignores some misplaced keys silently rather than erroring.
To resolve config errors efficiently, adopt a consistent workflow. Edit the config, then run swiftgen config run from the terminal so you see complete error output, and use SwiftGen's config lint to catch structural issues before generating. Fix one error at a time from the top, since a YAML parse failure hides everything below it — resolve structure first, then template names, then paths, then parser-specific keys. Keep the official SwiftGen configuration and per-parser documentation open, because the authoritative list of parsers, built-in template names, and valid keys is version-specific and the surest reference. After the config generates cleanly in the terminal, only then wire it back into your build phase or plugin, so you never debug config problems and build-integration problems at the same time. Pin your SwiftGen version so a config that works today does not break when an upgrade renames a template or changes a key. Finally, keep the config minimal — start with one parser, confirm it works, and add parsers incrementally — so that when an error appears you know exactly which recent change introduced it and can correct it immediately. Committing a known-good swiftgen.yml alongside a pinned version gives you a baseline you can always return to, so an experiment that breaks generation is a quick revert rather than a debugging session.
Run swiftgen config run directly in Terminal rather than through an Xcode build phase, which can truncate output. SwiftGen also offers a config lint command to check structure without generating.
The templateName is misspelled, does not exist for that parser, or changed between SwiftGen versions. Built-in templates are parser-specific, so verify the exact name against the documentation for your installed version.
Paths resolve relative to the config file or to input_dir if set. Check the path from the config's own directory and watch for case mismatches, moved files, or repeating the input_dir base in each path.
Inside the outputs block for that parser, not at the parser's top level. Misplacing them causes unknown-key errors or silently ignored settings.
A defined set including xcassets, strings, fonts, ib (Interface Builder), json, yaml, plist, and coredata, among others. Using a parser name outside the supported set fails; check the documentation for the current list.
Template names and keys can change across major versions. Pin your SwiftGen version so upgrades are deliberate, and when you do upgrade, re-check template names and parser keys against the new version's documentation.