Kometa debug review

Kometa Debug Review

Review first. Diagnose by file type and structure before suggesting edits.

Output contract

Always use these sections in this order:

Target file type
valid
wrong file type
wrong nesting
missing dependency
unsafe assumption
fixed YAML

If a section has no issue, say none.

If the input is a log excerpt rather than YAML:

• still use the same sections
• put the smallest relevant fix snippet under fixed YAML
• if the log proves the issue is operational rather than structural, fixed YAML can be none

Goal

• Name the intended file type.
• Catch wrong top-level keys and wrong indentation.
• Catch valid YAML that sits in the wrong Kometa file.
• Catch missing connector setup for builders.
• Read log excerpts and map them back to the real config or clean-art problem.

High-frequency failures

• collections: pasted into config.yml
• playlists: nested under libraries
• metadata: used where the user actually wants a collection builder
• overlay_files used correctly in config.yml but raw overlays: body pasted there too
• bad indentation under overlay: or under list items
• trying to combine multiple builders in a playlist
• using default-only template_variables as if they work everywhere
• template variable declared as both default and optional
• external_templates or raw collections: pasted into config.yml
• smart_label used without a real builder or with smart-filter criteria nested in the wrong place
• default ratings pack called with no meaningful template variables
• invented default-pack toggles like use_hbo or use_pixar on packs that do not expose them
• TMDb region or watch-region values using the wrong case or shape
• Trakt share links used instead of standard browser list URLs
• MDBList multi-list values packed into one comma string
• Letterboxd treated like a TV-capable source
• MAL search blocks with no real subattributes
• Trakt or MDBList builders with no matching connector in config.yml
• dynamic collections missing required type or data
• metadata edits placed at the wrong hierarchy level for seasons, episodes, albums, or tracks
• report_path placed under root settings: instead of the library
• operations placed under root settings: instead of the library
• schedule placed inside a plain operations mapping instead of scheduled operation list items
• report_path placed inside a file block instead of the library
• asset-first overlay configs missing assets_for_all
• reapply_overlays: true left on with poster-reset workflows
• overlay failures caused by already-overlaid art or corrupt backup posters

Review rules

• First decide intended file type.
• First decide if the input is YAML or logs.
• Then validate top-level keys for that file type.
• Then validate nesting.
• Then validate external dependency assumptions.
• Then validate runtime and workflow assumptions like overlay bloat or bad clean-art handling.
• Then provide the smallest corrected YAML that addresses the real issue.

Log review rules

• Read [CRITICAL] first, then [ERROR]
• Use the item line above the error when it narrows the scope
• trakt_list requires Trakt to be configured means missing dependency, not bad nesting
• Playlist Error: Library: XYZ not defined means wrong Plex library name or missing library reference
• Plex Error: No Items found in Plex is often zero builder results, not malformed YAML
• This item's poster already has an Overlay means clean-art workflow failure, not a random setting toggle problem
• cannot identify image file ... Original Posters points to corrupt or unreadable clean-art backups
• Failed to parse URL points to a bad builder URL, not a missing connector
• Overlay Update Not Needed is a success message, not a failure
• for template review, check variable rules before assuming YAML indentation is the problem

Broken config example

libraries:
  Movies:
    collection_files:
      - default: basic
collections:
  Trending:
    trakt_trending: 10

Diagnosis:

• Target file type: config.yml
• wrong file type: collections: body belongs in a separate collection file

Broken overlay example

overlays:
  Resolution:
  builder_level: show
    plex_search:
      all:
        resolution.not: 4K

Diagnosis:

• Target file type: overlay file
• wrong nesting: builder_level is aligned incorrectly and the overlay body is malformed

Good local references

• evals/fixtures/broken-config-file-boundary.yml
• evals/fixtures/broken-overlay-nesting.yml
• evals/fixtures/broken-metadata-top-level.yml
• evals/fixtures/broken-collection-shape.yml
• evals/fixtures/broken-playlist-multi-builder.yml
• evals/fixtures/broken-report-path-placement.yml
• evals/fixtures/broken-operations-under-settings.yml
• evals/fixtures/broken-operation-schedule-map.yml
• evals/fixtures/broken-report-path-file-block.yml
• evals/fixtures/broken-asset-workflow-no-item-scan.yml
• evals/fixtures/broken-template-variable-conflict.yml
• evals/fixtures/broken-template-file-boundary.yml
• evals/fixtures/broken-smart-label-shape.yml
• evals/fixtures/broken-default-ratings-no-variables.yml
• evals/fixtures/broken-default-streaming-unsupported-region-toggle.yml
• evals/fixtures/broken-default-resolution-4k-library.yml
• evals/fixtures/broken-default-languages-human-names.yml
• evals/fixtures/broken-default-network-custom-toggle.yml
• evals/fixtures/broken-default-studio-custom-toggle.yml
• evals/fixtures/broken-tmdb-watch-region.yml
• evals/fixtures/broken-imdb-language-code.yml
• evals/fixtures/broken-trakt-share-link.yml
• evals/fixtures/broken-mdblist-comma-string.yml
• evals/fixtures/broken-letterboxd-tv-assumption.yml
• evals/fixtures/broken-mal-empty-search.yml
• evals/fixtures/risky-overlay-bloat-config.yml
• evals/fixtures/log-trakt-missing-config.log
• evals/fixtures/log-overlay-already-overlaid.log
• evals/fixtures/log-playlist-library-not-defined.log
• evals/fixtures/log-overlay-corrupt-original-poster.log
• evals/fixtures/log-plex-no-items-found.log
• references/cards/kometa--yaml.md
• references/cards/logs--reading.md
• references/cards/overlays--clean-art.md
• references/cards/config--operations.md
• references/cards/config--asset-workflow.md
• references/cards/config--reports.md
• references/cards/collections--smart-label.md
• references/cards/templates--conditionals.md
• references/cards/templates--reuse.md

Stopping condition

Finish when the user has a concrete diagnosis, the failure mode is classified clearly, and the smallest real fix is shown.