Log files and where to find them¶

Locating Log Files¶

The meta.log file can be found within the logs folder of your Kometa config folder [right next to config.yml].

meta.log is the most recent run of Kometa.

As new log files are created, the old ones get a numeric suffix added: meta-1.log. The most recent is always the one without a number at the end.

meta-1.log is the previous run, meta-2.log is the run before that, so on and so forth.

Old Naming Convention

In an older release of Kometa, prevous run logs followed the naming pattern of meta.log.1, meta.log.2 etc. These files can safely be renamed if you no longer require them.

Providing Log Files on Discord¶

You can drag-and-drop your meta.log file directly into Discord, you do not need to upload it to a third-party site unless it exceeds the 50mb size limit.

Please DO NOT manually extract, copy and paste text from your log files directly into Discord as the formatting can be difficult to read and can often redact parts of the log file that are important for full context.

Basic Log File Troubleshooting¶

Wondering how to troubleshoot Kometa and how to read through the meta.log?

Using a text editor like Visual Studio Code or Sublime Text is recommended

In all cases, the first step is to open the meta.log with your text editor and perform these steps:

Check that you are running the latest version of your branch. Your current version can be found in the meta.log file either below the Kometa ASCII art, or at the end of the run. If you are not on the latest version of your branch, you will see Newest Version: X.X.X below this. Ensure you upgrade to the latest version of Kometa.
When scanning your meta.log file, search for [CRITICAL] items first as these will definitely need to be fixed
Scan your meta.log file for [ERROR] and make a note of the content of the full line to start your search below on how to resolve

Checking Kometa Version¶

Checking the version: You will find that in your meta.log around the 8th-10th line and will look something like this:

|                                 |
|     Version: 1.19.1-develop10   |
|=================================|

If you are not on the latest version of your branch, you will see Newest Version: X.X.X below this. Ensure you upgrade to the latest version of Kometa.

|                                       |
|     Version: 1.19.1-develop10         |
|     Newest Version: 1.19.1-develop20  |
|=======================================|

Understanding Log File Event Types¶

There are five main event types that you need to be aware of when understanding the log files, detailed below:

Type	Short Info	Description	Recommendation
`INFO`	Information log	Informational message that does not require much attention	No action required
`DEBUG`	Debug Log	Debug log message that does not require much attention	No action required
`WARNING`	Warning Log	Warning message that may require your attention	Read the warning and determine if this is something you need to take action on or not
`ERROR`	Error Log	Error message that in MOST cases requires action on your part to resolve	Read the error message, look for the message below and try recommendations
`CRITICAL`	Critical Log	Critical message requiring you to fix it for Kometa to run properly	Read the critical message and take appropriate action. look for message below and try recommendations

Common Log File Messages¶

This section aims to explain some commonly seen event messages that are produced in the logs.

CRITICAL¶

This table details examples of the most commonly-seen [CRITICAL] events and what they mean for the user.

Type	Short Info
`CRITICAL`	`Failed to Connect to https://api.themoviedb.org/`
Description: Current step Kometa was on made an API call to TMDb, but it aborted and moved on Recommendation: Determine if TMDb was offline and not replying to API requests. Try again and see if it fails again or not.

ERROR¶

This table details examples of the most commonly-seen [ERROR] events and what they mean for the user.

Type	Short Info
`ERROR`	`Playlist Error: Library: XYZ not defined`
Description: Plex library XYZ is not found Recommendation: Ensure that your config file has defined the proper library name as found in Plex
`ERROR`	`Plex Error: resolution: No matches found with regex pattern XYZ`
Description: While looking for a pattern in Plex, this one was not found Recommendation: This may be normal and require 0 actions. However, if you expect that Plex should have returned records, check the pattern to ensure it is working properly
`ERROR`	`Plex Error: No Items found in Plex`
Description: While using the Kometa Builder, no items with that criteria were returned from Plex Recommendation: This may be normal and require 0 actions. However, if you expect that Plex should have returned records, check the Builder to ensure it is working properly
`ERROR`	`IMDb Error: Failed to parse URL:`
Description: While using the Kometa Builder, url does not exist Recommendation: This may be normal and require 0 actions. However, if you expect that the URL should have returned records, check the url in your browser to ensure it is working properly
`ERROR`	`MDBList Error: No TVDb ID found for Nightfall (2022)`
Description: Online sources are missing information Recommendation: These sorts of errors indicate that the thing can't be cross-referenced between sites. For example, at the time of that error, the MDBList record for "Nightfall (2022)" didn't contain a TVDb ID. This could be because the record just hasn't been updated, or because "Nightfall (2022)" is not listed on TVDb. The fix is for someone [like you, perhaps] to go to the relevant site and fill in the missing data.
`ERROR`	`MDBList Error: Not Found`
Description: Online sources are missing information Recommendation: These sorts of errors indicate that the thing can't be cross-referenced between sites. For example, at the time of that error, the MDBList record was trying to get a rating for a media item and could not find it.
`ERROR`	`Plex Error: actor: Mel B not found`
Description: Actor not found and hence unable to create the collection Recommendation: Report error in #kometa-help channel and see if there is a fix.
`ERROR`	`Input Failed`
Description: A token or password is no longer valid for an online source of information Recommendation: Review the meta.log for more information
Description: You are using a builder that has not been configured yet. Recommendation: Review the meta.log for more information on what went wrong. Refer to the wiki for details on how to set this up

WARNING¶

This table details examples of the most commonly-seen [WARNING] events and what they mean for the user.

Type	Short Info
`WARNING`	`Convert Warning: No TVDb ID Found for TMDb ID: 15733`
Description: Online sources are missing information Recommendation: These sorts of errors indicate that the thing can't be cross-referenced between sites. For example, at the time of that error, the TMDb record for "The Two Mrs. Grenvilles" [ID 15733] didn't contain a TVDb ID. This could be because the record just hasn't been updated, or because "The Two Mrs. Grenvilles" is not listed on TVDB. The fix is for someone [like you, perhaps] to go to the relevant site and fill in the missing data.
`WARNING`	`Convert Warning: AniDB ID not found for AniList ID: 21400`
Description: Online sources are missing information Recommendation: These sorts of errors indicate that the thing can't be cross-referenced between sites. The fix is for someone [like you, perhaps] to go to the relevant site and fill in the missing data.
`WARNING`	`Convert Warning: No TVDb ID or IMDb ID found for AniDB ID: 14719`
Description: Online sources are missing information Recommendation: These sorts of errors indicate that the thing can't be cross-referenced between sites. The fix is for someone [like you, perhaps] to go to the relevant site and fill in the missing data.
`WARNING`	`Convert Warning: AniDB ID not found for MyAnimeList ID: 36838`
Description: Online sources are missing information Recommendation: These sorts of errors indicate that the thing can't be cross-referenced between sites. The fix is for someone [like you, perhaps] to go to the relevant site and fill in the missing data.

INFO¶

This table details examples of the most commonly-seen [INFO] events and what they mean for the user.

Type	Short Info
`INFO`	`Detail: TMDb_person updated poster to [URL]`
Description: Person image was downloaded from TMDb Recommendation: May require you to update the people poster image to your style or request it in the style of the Kometa defaults people posters

Other Troubleshooting Examples¶

The Log files will contain a great deal of detail about what exactly is happening and why. Generally speaking, if you're having a problem with Kometa the answer will be found here. These logs can of course be quite technical, but often the error can be relatively clear:

Something's missing from the format of the file:

| Loading Collection File: config/TV Shows.yml                                                       |
|                                                                                                    |
| YAML Error: metadata, collections, or dynamic_collections attribute is required                    |

The problem in that case was:

templates:
  Collection:
    cache_builders: 30
    sync_mode: sync
    sort_title: ZZZ-<<source>>-<<collection_name>>

collections:   <<< THIS LINE WAS MISSING
  Cached for 30 Days:
    template: {name: Collection, source: Looper}
    summary: ""
    mdblist_list: mdblist_list: https://mdblist.com/lists/stealthgyro/marvel-cinematic-universe-mcu

YAML doesn't allow duplicate keys:

| Loading Collection File: config/Anime.yml                                                          |
|                                                                                                    |
| YAML Error: while constructing a mapping
|   in "<unicode string>", line 27, column 5:
|         mal_favorite: 50
|         ^ (line: 27)
| found duplicate key "collection_order" with value "custom" (original value: "custom")
|   in "<unicode string>", line 32, column 5:
|         collection_order: custom
|         ^ (line: 32)

The problem there was something like this:

templates:
  Collection:
    cache_builders: 30
    sync_mode: sync
    sort_title: ZZZ-<<source>>-<<collection_name>>

collections:   <<< THIS LINE WAS MISSING
  Cached for 30 Days:
    template: {name: Collection, source: Looper}
    collection_order: custom                         <<<<  THIS KEY
    summary: ""
    collection_order: custom                         <<<<  DUPLICATED HERE
    mdblist_list: mdblist_list: https://mdblist.com/lists/stealthgyro/marvel-cinematic-universe-mcu

File is not where Kometa expects it:

| Loading Collection File: config/Movies.yml                                              |
| YAML Error: File Error: File does not exist /Users/Lucky/Kometa/config/Movies.yml       |

Source integrity¶

Source integrity is checked alongside the startup system information, with a maximum wait of 30 seconds for both cached file checking and baseline retrieval. The log reports Source Integrity: Verified, Source Integrity: MODIFIED, or Source Integrity: Check unavailable with a reason and an explanation that local files were not verified. If the startup time limit is reached, Kometa continues with Source Integrity: Check unavailable (startup time limit reached; local files were not verified). There is no later integrity result during library processing. The end-of-run Source Integrity Summary (startup check) repeats the startup result without waiting for or adopting a late result. A timeout in this summary describes the startup check, not a detected file change. Modified installations list changed, missing, and added files. An unavailable check means the comparison could not be completed; it does not indicate detected file changes. Only MODIFIED reports confirmed differences. This is a support diagnostic and never prevents Kometa from running.

The diagnostic is enabled by default. Use --no-source-integrity or set KOMETA_SOURCE_INTEGRITY=false to disable it, including file checks and network requests. Use --source-integrity or KOMETA_SOURCE_INTEGRITY=true to enable it. As with other runtime options, environment variables take precedence over CLI flags. Disabled checks report Source Integrity: Disabled (source-integrity option) in the startup header and end-of-run summary.

The baseline comes from official upstream source pinned to the installed commit. It is cached under .source-integrity/ in the active config directory for subsequent offline checks. After a new cache is successfully saved, Kometa retains it and the two most recently written other caches for the same repository and installation profile. This limits storage growth while allowing installations at different commits to share a config directory without evicting each other on every update. Downloads use temporary disk files. Upstream retrieval has a separate 180-second deadline, so a slow download can continue after the 30-second startup wait. If the process remains running and retrieval completes within that deadline, the worker can silently save the baseline for a later run; it does not log another result or change the startup result repeated in the summary. Scheduled starts for the same installation, config directory, and profile reuse an active check rather than launching another download. Each start still has its own 30-second wait and saved startup result. The worker is a daemon: if Kometa exits before retrieval completes, no baseline is saved and the next run retries.

Runtime config, logs, virtual environments, compiled Python files, desktop metadata, and integrity metadata are excluded. Differences consisting only of Windows versus Unix line endings are tolerated in known text files; binary files require exact bytes. Docker checks Kometa-owned files and directories rather than the container operating system. Repository-only CI/test files excluded from upstream source archives are outside the comparison.

Git installs use the installation's HEAD; Docker builds carry KOMETA_GIT_SHA when provided; .kometa_sha is an identity hint when present. The candidate commit must belong to an official upstream branch before a baseline is cached. PR and test images whose commits are outside official upstream history report Check unavailable. Older images or installations without exact commit metadata also report Check unavailable; recreate the container with an image containing that metadata. Cache corruption, unavailable upstream data, and inspection errors report Check unavailable. The diagnostic cannot protect against deliberate replacement of its own implementation or provenance metadata.