Developer Console
Sign In
Sign In
Developer Console

Catalog Ingestion Report Messages

A catalog data format (CDF) ingestion report is generated for each catalog file that an Amazon Fire TV client uploads to Amazon. The report states whether the catalog file was successfully integrated into Fire TV's universal browse and search. If it was not, the report provides details that explain the failure. The report also provides warnings and suggestions that can be used to improve the file.

This page lists errors, warnings, and suggestions seen in an ingestion report, explains their cause, and suggests a resolution to each situation. For more information on obtaining and using your ingestion report, see Verify the Uploaded CDF File.

Requirements

Readers should have at least a basic knowledge of working in an XML file (you know what elements and attributes are and know to close your tags) and be familiar with the information the information in Verify the Uploaded CDF File.

Who Should Fix These Problems?

In general, catalog files are created in one of two ways:

  • Automatically, with metadata information pulled from a media database. This is accomplished through a script or other code that grabs the data on a preordained schedule, transforms it into a CDF-compliant catalog file, and uploads it to your S3 bucket. This is the preferred method because once it's working correctly, it will run without the need for human interaction.
  • Manually, with someone maintaining the catalog file over time.

If your company uses the automated method, some fixes and changes must be made in the source database itself rather than the catalog file. Database access is often restricted to database administrators, so work with them to either allow you access or to make the changes for you. You might also have to work with developers to perfect the code that creates the CDF file from the data.

If your company maintains your catalog manually, access is probably less restrictive.

Be aware that in the case of large catalogs it isn't unusual to see warnings and suggestions that number in the thousands. Normally they're only a handful of warnings, just applied to thousands of entries. These don't tend to be issues that can be fixed through a blanket search-and-replace change.

For instance, a suggestion to add cast and crew information to 10,000 entries requires addressing each entry individually. Warnings and suggestions do not prevent your catalog from being used, so if and when you address them depends on your time and resources.

Conventions Used in This Document

The "CDF file" is the catalog data file you upload to Amazon, upon which the ingestion report is based. It is an XML file that conforms to the catalog data format (CDF) schema. See Step 1: Create Your Catalog File for details on the file contents.

WorkID is the ID of the work element (Movie, TvShow, TvSeason, TvEpisode, MiniSeries, MiniSeriesEpisode, or Extra) in which the issue was found. For instance, in the case of a movie it refers to the value of an ID element under a movie entry in your CDF file. Each message in the ingestion report expands to show the ID of each work that caused that message.

Detail message is the additional text you'll see for each WorkID when you expand a particular error, warning, or suggestion in the report. It provides more specific information about the message's cause in relation to that work. Not all messages have detail messages, in which case you only see the WorkID.

Nested elements are given using a period notation. For instance, TvEpisode.Credits.CrewMember refers to the CrewMember element that is a child of the Credits element that is in turn a child of the TvEpisode element. Movie.ID is an ID element that is the child of a movie element.

Anything in italics not used for emphasis is a placeholder for an actual value; nn for a number, ss for a text string, url for a full URL, etc.

Ellipses (…) used in examples indicate that some material not related to the topic was omitted in the interests of brevity and clarity.

Errors

Any message in the Errors section of your ingestion report causes your CDF file to be rejected. Correct all reported errors and then resubmit the CDF file.

Errors

Error: Invalid catalog file

Detail message: Unable to parse provided catalog

What went wrong

The CDF file is invalid. It's unlikely that you'll see this message; instead, you'll see XML validation failure messages.

What to do

Use a tool such as Xmllint or the validation plug-in for Notepad++ to validate your file and point you to errors. An invalid file can be caused by many things: omitting a closing tag, using an undefined element (which can simply be a typo — and also remember that XML is case-sensitive), putting the elements in the wrong order, or not including a required element or attribute. To avoid this error, you should always validate your file before you submit it.

See also

Error: ID is not unique

Detail message: WorkID nn works have this ID

Example: tt123456 6 works have this ID

What went wrong

Your file has at least two entries that have the same ID. Each work (Movie, TvShow, TvSeason, TvEpisode, etc.) in your CDF file must have a unique ID.

What to do

Find each of the works with this ID (tt123456 in the example) in your CDF file. Change the ID for all but one of them, making sure that you generate unique IDs for those you change. If the source of your CDF file is a database, you might use the work's database key as part of its ID to ensure uniqueness. Have an ID scheme and stick to it.

Possible elements involved

WorkType.ID
WorkType can be Movie, TvShow, TvSeason, TvEpisode, MiniSeries, MiniSeriesEpisode, or Extra

Error: MiniSeriesEpisode references an invalid MiniSeriesID

Detail message: WorkID

Example: tt123456 MiniSeriesEpisode references an invalid MiniSeriesID

What went wrong

The MiniSeriesEpisode with the given work ID (tt123456 in the example) has a MiniSeriesID element, but it's blank.

What to do

In your CDF file, find the MiniSeries element to which this episode should belong. If it is present, note its ID value. Go to the MiniSeriesEpisode's entry, locate its MiniSeriesID element, and change the value to match the MiniSeries ID. That is, ensure that MiniSeries.ID = MiniSeriesEpisode.MiniSeriesID.

If the MiniSeries element isn't present and you're not going to add it, use MiniSeriesEpisode.MiniSeriesTitle instead of MiniSeriesEpisode.MiniSeriesID. MiniSeriesEpisode.MiniSeriesTitle is used as given, without having to match anything. This should be done only in the absence of a MiniSeries element.

Elements possibly involved

MiniSeries.ID
MiniSeriesEpisode.MiniSeriesID
MiniSeriesEpisode.MiniSeriesTitle

Error: Referenced MiniSeries not found

Detail message: WorkID MiniSeriesEpisode references a missing MiniSeries with ID of ss

Example: tt123456 MiniSeriesEpisode references a missing MiniSeries with ID of nn654321

What went wrong

The MiniSeriesEpisode with the given work ID (tt123456 in the example) specifies the ID of its MiniSeries (nn654321 in the example), but there's no matching MiniSeries in your catalog.

What to do

In your CDF file, find the MiniSeries element to which this episode should belong. If it is present, note its ID value. Go to the MiniSeriesEpisode's entry, locate its MiniSeriesID element, and change the value to match the MiniSeries ID. That is, ensure that MiniSeries.ID = MiniSeriesEpisode.MiniSeriesID.

If the MiniSeries element isn't present and you're not going to add it, use MiniSeriesEpisode.MiniSeriesTitle instead of MiniSeriesEpisode.MiniSeriesID. MiniSeriesEpisode.MiniSeriesTitle is used as given, without having to match anything. This should be done only in the absence of a MiniSeries element.

Elements possibly involved

MiniSeries.ID
MiniSeriesEpisode.MiniSeriesID
MiniSeriesEpisode.MiniSeriesTitle

Error: Referenced TvSeason not found

Detail message: WorkID TvEpisode references a missing TvSeason with ID of ss

Example: tt123456 TvEpisode references a missing TvSeason with ID of nn654321

What went wrong

The TvEpisode with the given work ID (tt123456 in the example) specifies the ID of its TvSeason (nn654321 in the example), but there's no matching TvSeason in your catalog.

What to do

In your CDF file, find the TvSeason element to which this episode should belong. If the TvSeason is present, note its ID value. Go to the TvEpisode's entry, locate its SeasonID element, and change the value to match the TvSeason's ID. That is, ensure that TvSeason.ID = TvEpisode.SeasonID.

If the TvSeason isn't present and you're not going to add it, use TvEpisode.SeasonInShow instead of TvEpisode.SeasonID. You can also add the optional TvEpisode.SeasonTitle. TvEpisode.SeasonInShow and TvEpisode.SeasonTitle are used as given and are not required to match anything. This should be done only in the absence of a TvSeason element, which only should be absent if you absolutely cannot obtain that information.

Elements possibly involved

TvSeason.ID
TvEpisode.SeasonID
TvEpisode.SeasonInShow
TvEpisode.SeasonTitle

Error: Referenced TvShow not found

Detail messages:

WorkID TvEpisode references a missing TvShow with ID of ss

Example: tt123456 TvEpisode references a missing TvShow with ID of nn654321

What went wrong

This can happen with a TvEpisode. The episode with the given work ID (tt123456 in the example) specifies the ID of its TvShow (nn654321 in the example), but there's no matching TvShow in your catalog.

What to do

In your CDF file, find the TvShow element to which the episode should belong. If the TvShow is present, note its ID value. That is, ensure that TvShow.ID = TvEpisode.ShowID.

If the TvShow isn't present and you're not going to add it, use ShowTitle instead of ShowID. ShowTitle is used as given and is not required to match anything. This should be done only in the absence of a TvShow element, which should raise the question of whether one should be added.

Elements possibly involved

TvShow.ID
TvEpisode.ShowID
TvEpisode.ShowTitle

Error: Title is required and cannot be blank

Detail message: WorkID

What went wrong

Your CDF file contains a Title element for the given ID, it just doesn't contain the title text.

What to do

Find the work with the given ID in your CDF file, locate its Title element, and provide the text. Here's an example:

Before: <Title locale="en-US"></Title>
After: <Title locale="en-US">City Lights</Title>

Possible elements involved

WorkType.Title
WorkType can be Movie, TvShow, TvSeason, TvEpisode, MiniSeries, MiniSeriesEpisode, or Extra

Error: Too many invalid images

See Image-Related Messages.

Error: TvEpisode references an invalid SeasonID

Detail message: WorkID

Example: tt123456 TvEpisode references an invalid SeasonID

What went wrong

The TvEpisode with the given work ID (tt123456 in the example) has a SeasonID element, but it's blank.

What to do

In your CDF file, find the TvSeason element to which this episode should belong. If it is present, note its ID value. Go to the TvEpisode's entry, locate its SeasonID element, and change the value to match the TvSeason ID. That is, ensure that TvSeason.ID = TvEpisode.SeasonID.

If the TvSeason element isn't present and you're not going to add it, use TvEpisode.SeasonInShow instead of TvEpisode.SeasonID. TvEpisode.SeasonInShow is just a number, used as given. You can also add the optional TvEpisode.SeasonTitle element, which is also used as given, without having to match anything. This should be done only in the absence of a TvSeason element.

Elements possibly involved

TvSeason.ID
TvEpisode.SeasonID
TvEpisode.SeasonInSeries
TvEpisode.SeasonTitle

Error: TvEpisode references an invalid ShowID

Detail message: WorkID

Example: tt123456 TvEpisode references an invalid ShowID

What went wrong

The TvEpisode with the given work ID (tt123456 in the example) has a ShowID element, but it's blank.

What to do

In your CDF file, find the TvShow element to which this episode should belong. If it is present, note its ID value. Go to the TvEpisode's entry, locate its ShowID element, and change the value to match the TvShow ID. That is, ensure that TvShow.ID = TvEpisode.ShowID.

If the TvShow isn't present and you're not going to add it, use TvEpisode.ShowTitle instead of TvEpisode.ShowID. ShowTitle is used as given and is not required to match anything. This should be done only in the absence of a TvShow element.

Elements possibly involved

TvShow.ID
TvEpisode.ShowID
TvEpisode.ShowTitle

Warnings

Warnings do not cause the catalog ingestion to fail (except image-related warnings, which can if there are enough of them), but they should be addressed as your resources allow. Deprecation warnings in particular call for attention because they tell you that the CDF schema has changed, which can result in some of your data no longer being used as before.

Warnings

Aspect ratio should be between %f and %f (%f to %f preferred.)
Copyright is optional but should not be blank if supplied
CastMember or CrewMember name should not be blank
ExternalID is optional but should not be blank if supplied
Image height must be greater than %d pixels (greater than %d pixels preferred)
Inconsistent release year information
Invalid image
MiniSeries is not associated with any MiniSeriesEpisodes
Possible invalid string found for optional CastMember Role element
Quality element in Offer is deprecated in favor of Quality element in LaunchDetails
ReleaseInfo element is deprecated
Role (character name) is optional but should not be blank if supplied
Runtime minutes is not within expected range of 1 to 2880 minutes
The ShortDescription should not be the same as the Title
The Synopsis should be longer and more descriptive than the ShortDescription
The Synopsis should not be the same as the ShortDescription
The Synopsis should not be the same as the Title
Text contains characters that are escaped more than once
TvSeason is not associated with any TvEpisodes
TvShow is not associated with any TvEpisodes
Unsupported image type. Provided image not JPG or PNG format

See Image-Related Messages. Note that this message can appear as either a warning or a suggestion, depending on its severity.

Detail message: WorkID

What went wrong

The Copyright element is present under the work with the given ID, but it doesn't have the copyright information text.

What to do

Because the Copyright element is optional, you can delete it altogether if you don't know the copyright information. Otherwise, find the work element with the given ID in your CDF file, locate its Copyright element, and add the missing information. Here's an example:

Before: <Copyright locale="en-US"></Copyright>
After: <Copyright locale="en-US">© 1894 Edison Manufacturing Company</Copyright>

Possible elements involved

WorkType.Copyright
WorkType can be Movie, TvShow, TvSeason, TvEpisode, MiniSeries, MiniSeriesEpisode, or Extra

Warning: CastMember or CrewMember name should not be blank

Detail message: WorkID

What went wrong

This warning can apply to either a CastMember or a CrewMember. Your CDF file contains the Name element for the person, but it's missing the person's name.

What to do

Find the work element with the given ID in your CDF file. Find that work's Credits element. Look at each CastMember or CrewMember element in that Credits section, locate any with an empty Name element, and add that information. Here's an example:

Before: <Name locale="en-US"></Name> After: <Name locale="en-US">Alan Smithee</Name>

Possible elements involved

WorkType.CastMember.Name
WorkType.CrewMember.Name
WorkType can be Movie, TvShow, TvSeason, TvEpisode, MiniSeries, MiniSeriesEpisode, or Extra

Warning: ExternalID is optional but should not be blank if supplied

Detail message: WorkID

What went wrong

Your CDF file contains an ExternalID element, but doesn't provide the information. An ExternalID is the ID assigned to a work or person by some other source such as IMDb or the UPC code on a DVD box. The ExternalID can apply to a work (Movie, TvShow, etc.), a CastMember, or a CrewMember. With an ExternalID, we can link to or pull in information from that source. For instance, for a member of the cast or crew, their IMDb ExternalID allows their picture and description to be imported.

What to do

Find the element with the given ID in your CDF file. Find each ExternalID element that it contains—a work can contain as many ExternalID elements as it has CrewMember or CastMember elements, plus one for the work itself. Because the ExternalID element is optional, you can delete it altogether if necessary. Otherwise, add the missing information. Here's an example for a CastMember:

<Movie>
    <ID>_WorkID_</ID>
    <ExternalID scheme="imdb">tt0029843</ExternalID>
    ...
    <Credits>
        <CastMember>
            <Name locale="en-US">Errol Flynn</Name>
            <ExternalID scheme="imdb">nm0653028</ExternalID>

Possible elements involved

WorkType.ExternalID
WorkType.CastMember.ExternalID
WorkType.CrewMember.ExternalID
WorkType can be Movie, TvShow, TvSeason, TvEpisode, MiniSeries, MiniSeriesEpisode, or Extra

See Image-Related Messages. Note that this message can appear as either a warning or a suggestion, depending on its severity.

Warning: Inconsistent release year information

Detail message: WorkID Provided ReleaseYear yyyy differs from the year yyyy in the ss element

Examples:

tt123456 Provided ReleaseYear 1959 differs from the year 1960 in the OriginalAirDate element
tt456789 Provided ReleaseYear 1977 differs from the year 1978 in the ReleaseDate element

What went wrong

The work specifies its release year in more than one place, but they do not agree. You've provided a ReleaseYear plus an OriginalAirDate or ReleaseDate, each of which also include a year. In tracking this down, note that there are two different ReleaseDate elements, one that's a direct child element of the work and another that's a child element of the deprecated ReleaseInfo element. ReleaseDate is found only under Movie, TvShow, and MiniSeries elements. The deprecated ReleaseInfo.ReleaseDate is found in all work types. OriginalAirDate is found only under TvEpisode and MiniSeriesEpisode elements.

What to do

Find the element with the given WorkID (tt123456 or tt456789 in the example) in your CDF file. Find its ReleaseYear element, verify that the year is correct, and note the value. Next, find any instance of OriginalAirDate or ReleaseDate under that work and ensure that those strings include the same year. Note that OriginalAirDate and ReleaseDate have strict data forms (for example, 2003-08-08T00:00:00Z) of which the year might be only a portion.

Possible elements involved

WorkType.ReleaseYear
WorkType.ReleaseDate
WorkType.ReleaseInfo.ReleaseDate
WorkType can be Movie, TvShow, TvSeason, TvEpisode, MiniSeries, MiniSeriesEpisode, or Extra

Warning: Invalid image

See Image-Related Messages.

Warning: MiniSeries is not associated with any MiniSeriesEpisodes

Detail message: WorkID

What went wrong

Your CDF file contains an entry for a MiniSeries, but it doesn't have any episodes. This can lead to a bad user experience because they can see and select the mini-series, but then find it empty. There are two possibilities for what caused this. The first is that the MiniSeriesEpisode elements weren't included in the CDF file. The second is that those episodes are in your CDF file, but they specify the wrong mini-series.

What to do

Find each expected MiniSeriesEpisode element for that MiniSeries in your CDF file. Are they there?

  • No: You'll need to add them.
  • Yes: How does each identify its MiniSeries; by using the MiniSeriesID or MiniSeriesTitle element?
  • MiniSeriesID: Ensure that it matches the MiniSeries.ID value (the WorkID in the detail message).
  • MiniSeriesTitle: Ensure that it matches the MiniSeries.Title value exactly, including case.

Possible elements involved

MiniSeries.ID
MiniSeries.Title
MiniSeriesEpisodes.MiniSeriesID
MiniSeriesEpisodes.MiniSeriesTitle

Warning: Possible invalid string found for optional CastMember Role element

Detail message: WorkID Please confirm that text is a valid Role (character name)

Examples:

tt123456 Please confirm that Actor is a valid Role (character name)
tt123456 Please confirm that Unknown is a valid Role (character name)

What went wrong

This warning is very specific. Currently, it only looks for values of "Unknown" or "Actor" in the CastMember.Role element. The Role element exists to supply the name of the character that the actor played in the work, such as Han Solo. Any entry under CastMember is, by definition, an actor. That said, there are rare instances where "Actor" or "Unknown" could be valid character names. In those cases, to avoid seeing this warning in every report, you might reword those entries somewhat if possible, such as "Actor #1" or "The Unknown". Note that if you include the Role element but leave it blank, you'll receive a different warning.

What to do

Find the work element with the given ID in your CDF file. Find its Credits section. Find any CastMember elements that it contains and locate any with "Actor" or "Unknown" in the Role element. The Role element is optional, so omit it altogether if you don't know the character's name. Otherwise, add the character name.

Possible elements involved

WorkType.Credits.CastMember.Role
WorkType can be Movie, TvShow, TvSeason, TvEpisode, MiniSeries, MiniSeriesEpisode, or Extra

Warning: Quality element in Offer is deprecated in favor of Quality element in LaunchDetails

Detail message: WorkID

What went wrong

The CDF schema has changed, but your file still uses elements from an older schema version. In this case, as of CDF version 1.2, the Quality element for each Offer type was moved under the new Offers.OfferType.LaunchDetails element, but is otherwise the same. Your file still places the Quality element directly under Offers.OfferType.

What to do

Technically, you don't have to do anything. Your existing Quality value will continue to be used. However, in the interest of a clean ingestion report, you should update your file as your resources allow.

  • If your CDF file is automatically generated from your media database: The script or transform that takes the information from your database and puts it into the CDF format will need to be updated. Contact your database administrator (DBA) and tell them that the quality value should now be exported to the Offers.OfferType.LaunchDetails.Quality element rather than to Offers.OfferType.Quality. The DBA can consult the Catalog Data Format (CDF) XSD for the LaunchElement's proper placement.
  • If your database has a structure that matches the CDF format: Again, your DBA will need to make this change. In this case, the database itself will need to be slightly redesigned to account for the newer CDF structure.
  • If you construct the CDF file manually: Find the work with the given ID in your CDF file. Find its Offers element. Do the following for each offer type that currently has an Offers. OfferType.Quality element:
    1. Add a LaunchDetails element. Location matters — it should be the last element in the SubscriptionOffer and FreeOffer types.
    2. Add a Quality element under the LaunchDetails element. Specify the same value (SD, HD, or UHD) that the original element used.
    3. Delete the original Offers.OfferType.Quality element.

Here's an example of the change:

Before

<Movie>
    ...
    <Offers>|
        <FreeOffer>
            <Quality>HD</Quality>
            ...
        </FreeOffer>
        ...
    </Offers>
    ...
</Movie>

After

<Movie>
    ...
    <Offers>|
        <FreeOffer>
            ....
            <LaunchDetails>
                <Quality>HD</Quality>
            </LaunchDetails>
        </FreeOffer>
        ...
    </Offers>
    ...
</Movie>

Possible elements involved

WorkType.Offers.OfferType.Quality (deprecated)
WorkType.Offers.OfferType.LaunchDetails.Quality
WorkType can be Movie, TvShow, TvSeason, TvEpisode, MiniSeries, MiniSeriesEpisode, or Extra
OfferType can be SubscriptionOffer or FreeOffer

Warning: ReleaseInfo element is deprecated

Detail message: WorkID Please use the ReleaseDate / OriginalAirDate / ReleaseYear element instead for WorkType

Examples:

tt123456 Please use the ReleaseDate element instead for ShowType
tt45678 Please use the OriginalAirDate element instead for EpisodeType

What went wrong

The CDF schema has changed, but your file still uses elements from an older schema version. In this case, as of CDF version 1.3, the ReleaseInfo element, which applied to all work types, is deprecated in favor of work-type-specific values. ReleaseInfo contained two child elements: ReleaseDate and ReleaseCountry. ReleaseCountry information is no longer used at all. ReleaseDate information is now stored based on the work type: ReleaseDate for the Movie, TvShow, and MiniSeries types; OriginalAirDate for TvEpisode and MiniSeriesEpisode types.

What to do

Technically, you don't have to do anything. Your existing ReleaseInfo.ReleaseDate value will continue to be used. However, in the interest of a clean ingestion report, you should update your file as your resources allow.

  • If your CDF file is automatically generated from your media database: The script or transform that takes the information from your database and puts it into the CDF format will need to be updated. Contact your database administrator (DBA) and tell them the following:
    • The work's release date, previously contained in WorkType.ReleaseInfo.ReleaseDate, should now be exported to WorkType.OriginalAirDate for TvEpisode, and MiniSeriesEpisode types and WorkType.ReleaseDate for Movie, TvShow, and MiniSeries types.
    • The ReleaseInfo element should be removed.

      The DBA can consult the Catalog Data Format (CDF) XSD for details.
  • If your database has a structure that matches the CDF format: Again, your DBA will need to make this change. In this case, the database itself will need to be slightly redesigned to account for the newer CDF structure.
  • If you construct the CDF file manually: Find the work with the given ID in your CDF file. Find its ReleaseInfo element and note the ReleaseDate value.
  • If the work type is Movie, TvShow, or MiniSeries: Add a ReleaseDate element, including the value, as the very last thing under the work's element.
  • if the work type is TvEpisode, or MiniSeriesEpisode: Add an OriginalAirDate element, including the value, as the very last thing under the work's element.
  • Regardless of work type: Remove the original ReleaseInfo element once the new elements are in place.

Elements possibly involved

WorkType.ReleaseInfo (deprecated)
WorkType.ReleaseInfo.ReleaseDate (deprecated)
WorkType.ReleaseInfo.ReleaseCountry (deprecated)
WorkType can be Movie, TvShow, TvSeason, TvEpisode, MiniSeries, MiniSeriesEpisode, or Extra

Movie.ReleaseDate
TvShow.ReleaseDate
MiniSeries.ReleaseDate
TvEpisode.OriginalAirDate
MiniSeriesEpisode.OriginalAirDate

Warning: Role (character name) is optional but should not be blank if supplied

Detail message: WorkID Role (character name) for ​person is blank

Example: tt123456 Role (character name) for Errol Flynn is blank

What went wrong

The Role element is present, but it doesn't provide the information. The Role element exists to supply the name of the character that the actor played in the work, such as Han Solo.

What to do

Find the work with the given ID in your CDF file (tt123456 in the example). Find its Credits section. Find the CastMember element for the person in question (Errol Flynn in the example), and locate that person's Role element. Role is optional, so you can either add the character name or, if you don't know the character name, delete the Role element altogether. Do not use "Unknown" as a character name.

Possible elements involved

WorkType.Credits.CastMember.Role
WorkType can be Movie, TvShow, TvSeason, TvEpisode, MiniSeries, MiniSeriesEpisode, or Extra

Warning: Runtime minutes is not within expected range of 1 to 2880 minutes

Detail message: WorkID Please confirm that nn minutes is the correct runtime

Example: tt123456 Please confirm that 99999999 minutes is the correct runtime

What went wrong

Your CDF file contains a RuntimeMinutes element with a value that seems unusually large or small. This warning is triggered when the value is less than 1 or greater than 2880 minutes (48 hours!). Few works would legitimately fall outside of that range. This information can be seen by the end user and so should be accurate to avoid a bad user experience.

What to do

Find the work with the given ID in your CDF file (tt123456 in the example). Find its RuntimeMinutes element. Make sure that the correct value is given. Because this is an optional element, you can delete the RuntimeMinutes element altogether, but for a better user experience this is not recommended.

Possible elements involved

WorkType.RuntimeMinutes
WorkType can be Movie, TvShow, TvSeason, TvEpisode, MiniSeries, MiniSeriesEpisode, or Extra

Warning: The ShortDescription should not be the same as the Title

Detail message: WorkID

What went wrong

The Title and ShortDescription elements contain identical text, which is a poor user experience. The ShortDescription element is meant to hold a 2-3 line summary of the work to give the user an idea of whether that work is of interest to them. Users already know the title at that point.

What to do

Find the work with the given ID in your CDF file. Find its ShortDescription element. Replace the work's name in that element with a brief (2-3 lines) description of its plot or subject. The ShortDescription element is optional; if you don't have a description, you can delete it altogether, although we recommended that each work has at least a ShortDescription.

Possible elements involved

WorkType.ShortDescription
WorkType can be Movie, TvShow, TvSeason, TvEpisode, MiniSeries, MiniSeriesEpisode, or Extra

Warning: The Synopsis should be longer and more descriptive than the ShortDescription

Detail message: WorkID

What went wrong

This CDF file contains both a ShortDescription and a Synopsis for this work. The Synopsis text is shorter than, but not identical to, the ShortDescription text. The Synopsis element is meant to hold a more detailed description of the work than can be given in the 2-3 line ShortDescription.

What to do

Find the work with the given ID in your CDF file. Find that work's Synopsis and ShortDescription elements and compare their contents. Adding an expanded Synopsis is the ideal solution for the best user experience. However, if you don't have any further information on the work, you can omit the Synopsis as it is optional. Although it is also optional, we recommend that you supply at least a shortDescription.

Possible elements involved

WorkType.ShortDescription
WorkType.Synopsis
WorkType can be Movie, TvShow, TvSeason, TvEpisode, MiniSeries, MiniSeriesEpisode, or Extra

Warning: The Synopsis should not be the same as the ShortDescription

Detail message: WorkID

What went wrong

This CDF file contains both a ShortDescription and a Synopsis for this work, and the two elements contain identical text. The Synopsis element is meant to hold a more detailed description of the work's content than can be given in the 2-3 line ShortDescription.

What to do

Find the work with the given ID in your CDF file. Find that work's Synopsis and ShortDescription elements and compare their contents. If the ShortDescription is more than 2-3 lines, shorten it. If not, then expand the Synopsis for the best user experience. However, if you don't have any further information on the work, you can omit the Synopsis as it is optional. Although it is also optional, we recommend that you supply at least a ShortDescription.

Possible elements involved

WorkType.ShortDescription
WorkType.Synopsis
WorkType can be Movie, TvShow, TvSeason, TvEpisode, MiniSeries, MiniSeriesEpisode, or Extra

Warning: The Synopsis should not be the same as the Title

Detail message: WorkID

What went wrong

The Title and Synopsis elements contain identical text, which is a poor user experience. The Synopsis element is meant to hold a summary of the content to give the user an idea of what the work is about. They already know the title by that point.

What to do

Find the work with the given ID in your CDF file. Find its Synopsis element. Replace the work's name in that element with a description of its plot or subject. The Synopsis element is optional, so if you don't have a description you can delete it altogether, although this is not ideal.

Possible elements involved

WorkType.Synopsis
WorkType can be Movie, TvShow, TvSeason, TvEpisode, MiniSeries, MiniSeriesEpisode, or Extra

Warning: Text contains characters that are escaped more than once

Detail message: WorkID Element contains characters that are escaped more than once

Examples:

tt123456 MiniSeriesTitle contains characters that are escaped more than once
tt234567 SeasonTitle contains characters that are escaped more than once
tt345678 ShortDescription contains characters that are escaped more than once
tt456789 ShowTitle contains characters that are escaped more than once
tt567890 Title contains characters that are escaped more than once

What went wrong

An XML serializer (possibly used in the code that pulls data from your database and converts it into the catalog XML file), has replaced the ampersand (&) in an escaped character with the escaped ampersand (&). An escaped character is present in your text as a code entity; for example, • for an em-dash, and & for an ampersand. The serializer did not expect escaped characters and dealt with them as plain text, escaping all ampersands. This results in "•" becoming "&mdash;" and displaying as "•". The string "this & that", which you expect to render as "this & that", becomes "this &amp; that", which displays as "this & that".

What to do

In both your CDF file and in your source database, find the work with the given ID and then its text element as specified in the detail message (Title, ShowTitle, SeasonTitle, ShortDescription, or MiniSeriesTitle). If the doubly-escaped characters are only present in your catalog file, the problem lies in the transformation when the catalog file is created. Use non-escaped characters in the original text whenever possible. You might also be able to instruct the serializer to expect an escaped string so that it properly recognizes those characters.

Possible elements involved

MiniSeriesEpisode.MiniSeriesTitle
TvEpisode.SeasonTitle
TvEpisode.ShowTitle
TvSeason.ShowTitle
WorkType.ShortDescription
WorkType.Title
WorkType can be Movie, TvShow, TvSeason, TvEpisode, MiniSeries, MiniSeriesEpisode, or Extra

Warning: TvSeason is not associated with any TvEpisodes

Detail message: WorkID

What went wrong

Your CDF file contains an entry for a TvSeason, but it doesn't have any episodes. This can lead to a bad user experience because they can see and select the season, but then find it empty. There are two primary possibilities for what caused this. The first is that the TvEpisode elements weren't included in the CDF file. The second is that those episodes are in your CDF file, but they specify the wrong season.

What to do

Find each expected TvEpisode element for that season in your CDF file. Are they there?

  • No: You'll need to add them.
  • Yes: How does each identify its season; by using the SeasonID or SeasonInShow element?
  • SeasonID: Ensure that it matches the TvSeason.ID value (the WorkID in the detail message).
  • SeasonInShow: Ensure that it matches the TvSeason.SeasonInShow value.

Possible elements involved

TvSeason.ID
TvEpisode.SeasonTitle
TvEpisode.SeasonID
TvEpisode.SeasonInShow

Warning: TvShow is not associated with any TvEpisodes

Detail message: WorkID

What went wrong

Your CDF file contains an entry for a TvShow, but it doesn't have any episodes. This can lead to a bad user experience because they can see and select the show, but then find it empty. There are two primary possibilities for what caused this. The first is that the TvEpisode elements weren't included in the CDF file. The second is that those episodes are in your CDF file, but they specify the wrong show.

What to do

Find each expected TvEpisode element for that show in your CDF file. Are they there?

  • No: You'll need to add them.
  • Yes: How does each identify its show; by using the ShowID or ShowTitle element?
  • ShowID: Ensure that it matches the TvShow.ID value (the WorkID in the detail message).
  • ShowTitle: Ensure that it matches the TvShow.Title value exactly, including case.

Possible elements involved

TvShow.ID
TvShow.Title
TvEpisode.ShowID
TvEpisode.ShowTitle

See Image-Related Messages.

Suggestions

Suggestions other than "Invalid image" do not prevent your catalog from being successfully updated. They are provided to encourage best practices for an improved end user experience.

Suggestions

Aspect ratio should be between %f and %f (%f to %f preferred.)
Image height must be greater than %d pixels (greater than %d pixels preferred)
Invalid image
Provide cast and crew information for better search and browse integration
Provide only one ShortDescription/Synopsis per locale
Provide the Count for CustomerRating for better data quality and user experience

See Image-Related Messages. Note that this message can appear as either a warning or a suggestion, depending on its severity.

See Image-Related Messages. Note that this message can appear as either a warning or a suggestion, depending on its severity.

Suggestion: Invalid image

See Image-Related Messages.

Suggestion: Provide cast and crew information for better search and browse integration

Detail message: WorkID

What to do

In your CDF file, this work does not include any cast or crew information. Including this information can make the work easier to find by the user. For instance, the user might want to search for movies that feature the actor Humphrey Bogart, or films directed by Akira Kurosawa. Without at least basic cast and crew information, the work can only be found by searching for its title or coming across it while browsing.

Elements involved

WorkType.Credits.CastMember
WorkType.Credits.CrewMember
WorkType can be Movie, TvShow, TvSeason, TvEpisode, MiniSeries, MiniSeriesEpisode, or Extra<br/.

Suggestion: Provide only one ShortDescription/Synopsis per locale

Detail message: WorkID There is more than one ShortDescription/Synopsis with locale of ss

Examples

WorkID There is more than one ShortDescription with locale of en-us
WorkID There is more than one Synopsis with locale of fr

What to do

Your CDF file contains either multiple entries with the same locale under ShortDescription, multiple entries with the same locale under Synopsis, or both. For a given locale, only one ShortDescription and one Synopsis can be used. Find the work with the given ID in your CDF file. Find its ShortDescription element. If the ShortDescription contains multiple entries, find any with the same locale value. Remove entries as needed to leave a single entry with that locale. Repeat the procedure for the Synopsis element.

Elements involved

WorkType.ShortDescription
WorkType.Synopsis
WorkType can be Movie, TvShow, TvSeason, TvEpisode, MiniSeries, MiniSeriesEpisode, or Extra

Suggestion: Provide the Count for CustomerRating for better data quality and user experience

Detail message: WorkID

What to do

The CustomerRating entry in your CDF file has the option of a Count element. Count is intended to state the number of customers who rated the work. Higher numbers give a rating more credibility, as they tend to balance out the skew that can result from a low sample set. You would need to track that information and update the Count and CustomerRating values each time you update your catalog.

Elements involved

WorkType.CustomerRating.Count
WorkType can be Movie, TvShow, TvSeason, TvEpisode, MiniSeries, MiniSeriesEpisode, or Extra

Image-Related Messages

Errors, warnings, and suggestions that concern images interact in a way that the other messages do not. Normally, warnings and suggestions do not cause your catalog to be rejected. However, image-related warnings and suggestions in over 50% of your entries trigger the Too many invalid images error, which does cause a catalog rejection.

Many image issues aren't a problem with the CDF file itself, but rather a problem with one or more images that it references. Solving some image issues can involve graphic design, image editing, or server access rights. You might need to reach out to your graphics or IT department to help you solve these problems.

Error-related messages

Error: Too many invalid images
Warning: Aspect ratio should be between 1:3 and 3:1 (1:2 to 2:1 preferred.)
Warning: Image height must be greater than 240 pixels (greater than 480 pixels preferred)

Warning: Invalid image

We were unable to retrieve an image from url. The HTTP response was empty.
We were unable to retrieve an image from url. The HTTP connection was unexpectedly closed.
We were unable to retrieve an image from url. The HTTP response was invalid.
We were unable to retrieve an image from url. The HTTP response was status code, reason.
Warning: Unsupported image type. Provided image not JPG or PNG format.
Suggestion: Aspect ratio should be between 1:3 and 3:1 (1:2 to 2:1 preferred.)
Suggestion: Image height must be greater than 240 pixels (greater than 480 pixels preferred)

Suggestion: Invalid image

No image present for item. Please provide image if available.

Error: Too many invalid images

Detail message: nn% invalid images or fewer allowed; nn% found. See the warnings and suggestions section for details.

What went wrong

A small number of invalid images (missing or unusable) do not cause an ingestion failure—you'll only see warnings and suggestions in that case. However, enough invalid images were found in this catalog to cause a failure. The threshold is approximately 50%. Note that the lack of an image for a work is considered an invalid image, so at least 50% of the works in your catalog must include valid images.

What to do

Refer to the Warnings and Suggestions sections of the ingestion report for the specific image-related issues encountered in the ingestion. Find and correct any instances of those warnings and suggestions that you find in the report.

Elements involved

WorkType.ImageUrl
WorkType can be Movie, TvShow, TvSeason, TvEpisode, MiniSeries, MiniSeriesEpisode, or Extra

Warning/Suggestion: Aspect ratio should be between 1:3 and 3:1 (1:2 to 2:1 preferred.)

Detail message: WorkID Unsupported aspect ratio nn for image url. Please provide acceptably sized image.

What went wrong

This is not a problem with your CDF file; it is a problem with an image that it references. The image exceeds our current height-to-width ratio requirements, which is to say that it's either too skinny or too flat.

What you need to know

We want a width-to-height ratio between 1:2 and 2:1. If your image is between 1:3 and 3:1, we crop it to 1:2 or 2:1 and this message appears as a suggestion. However, if the cropping causes the image height to drop below 240 pixels, the image won't be used.

If your image is outside of 1:3 to 3:1, this message appears as a warning and the image counts toward the total number of invalid images, which can lead to the catalog being rejected.

What to do

Find the work with the given ID (tt123456 in the example) in your CDF file. Find the ImageUrl tag that it contains. This URL tells you where the image file is located. Provide that URL to your graphics department and let them know that you need the image to have a width-to-height ratio between at least 1:3 and 3:1 (1:2 and 2:1 to avoid cropping), while ensuring that the height is no less than 480 pixels, even after cropping. Once you have a corrected image, ensure that its URL hasn't changed. If it has, update the ImageUrl value in your CDF file.

Possible elements involved

WorkType.ImageUrl
WorkType can be Movie, TvShow, TvSeason, TvEpisode, MiniSeries, MiniSeriesEpisode, or Extra

Warning: Image height must be greater than 240 pixels (greater than 480 pixels preferred)

Detail message: WorkID Image height nn is below acceptance criteria for url. Please provide acceptably sized image.

What went wrong

This is not a problem with your CDF file, but rather a problem with an image that it references. The image referenced by the work has a proper width-to-height ratio, but it is shorter than the required 480 pixels high. We prefer a height of at least 480 pixels. If your image height is between 240 and 480 pixels, this message appears as a suggestion. If your image height is below 240 pixels, this message appears as a warning and the image counts toward the total number of invalid images, which can lead to the catalog being rejected.

What to do

Find the element with the given ID in your CDF file. Find the ImageUrl tag that it contains. This URL tells you where the image file is located. Provide that URL to your graphics department and let them know that the image height should be no less than 240 pixels (480 pixels or more preferred) while ensuring that the image retains a width-to-height ratio between 1:3 or 3:1 (between 1:2 and 2:1 to avoid cropping). Once you have a corrected image, ensure that its URL hasn't changed. If it has, update the ImageUrl value in your CDF file.

Possible elements involved

WorkType.ImageUrl
WorkType can be Movie, TvShow, TvSeason, TvEpisode, MiniSeries, MiniSeriesEpisode, or Extra

Warning: Invalid image

Detail message: WorkID We were unable to retrieve an image from url. The HTTP response was empty.

What went wrong

The request to provide the image was made to the server where the image is stored, but, while the response code indicated success, the response contained no headers or body, and no image.

What to do

This is not a problem with the CDF file, but rather a server communication problem. If the problem persists in subsequent reports, find the work with the given ID in your CDF file and find its ImageUrl tag. Provide the URL to your IT department, let them know that retrieval requests for the image are coming back empty, and ask them to investigate.

Possible elements involved

WorkType.ImageUrl
WorkType can be Movie, TvShow, TvSeason, TvEpisode, MiniSeries, MiniSeriesEpisode, or Extra

Warning: Invalid image

Detail message: WorkID We were unable to retrieve an image from url. The HTTP response was unexpectedly closed.

What went wrong

The request to provide the image was made to the server where the image is stored, but the server connection closed unexpectedly and the image could not be retreived.

What to do

This is not a problem with the CDF file, but rather a server communication problem. In this case, wait for the next report to try to reproduce the issue, which might very well be a one-time problem. If the image request continues to return this warning, provide the image file's URL to your IT department and let them know that the system is repeatedly not responding to a retrieval request with a valid HTTP response. They should be able to further investigate based on that information.

Possible elements involved

WorkType.ImageUrl
WorkType can be Movie, TvShow, TvSeason, TvEpisode, MiniSeries, MiniSeriesEpisode, or Extra </br>

Warning: Invalid image

Detail message: WorkID We were unable to retrieve an image from url. The HTTP response was invalid.

What went wrong

The request to provide the image was made to the server where the image is stored, but the response message that came back was garbled in some way.

What to do

This is not a problem with the CDF file, but rather a server communication problem. In this case, you might wait for the next report to see if it replicates; it's entirely possible that it was a one-time problem. If the image request continues to return this warning, provide the image file's URL to your IT department and let them know that the system is repeatedly not responding to a retrieval request with a valid HTTP response. They should be able to further investigate based on that information.

Possible elements involved

WorkType.ImageUrl
WorkType can be Movie, TvShow, TvSeason, TvEpisode, MiniSeries, MiniSeriesEpisode, or Extra

Warning: Invalid image

Detail message: WorkID We were unable to retrieve an image from url. The HTTP response was status code: reason.

What went wrong

The request to provide the image was made to the server where the image is stored, but the response code indicated a problem and did not return an image.

What to do

This is not a problem with the CDF file, but rather a server communication problem. Provide the image file's URL and the response's status code and reason to your IT department. They should be able to further investigate based on that information. The problem could lie with an invalid request, a server accessibility or firewall issue, a payload size issue, an offline server, or any number of things.

Possible elements involved

WorkType.ImageUrl
WorkType can be Movie, TvShow, TvSeason, TvEpisode, MiniSeries, MiniSeriesEpisode, or Extra

See also

HTTP/1.1: Status Code Definitions

Warning: Unsupported image type. Provided image not JPG or PNG format.

Detail message: WorkID Unsupported image type ext for url. Images should be in JPG or PNG format.

What went wrong

The CDF file has specified an image file with a format other than JPG or PNG.

What to do

Find the work with the given ID in the CDF file. Find its ImageUrl element. This URL specifies the image file location. You might need to contact your graphics department to have the image converted to a supported format (JPG or PNG), or you can do it yourself by opening the file in a graphics program and saving it as one of the supported types. Some file type conversions can degrade the image, so compare the original and new versions to ensure that the new image is still acceptable. Replace the image on the server with the new version. You might need to update the ImageUrl element in the CDF file to match the new image name.

Possible elements involved

WorkType.ImageUrl
WorkType can be Movie, TvShow, TvSeason, TvEpisode, MiniSeries, MiniSeriesEpisode, or Extra

Suggestion: Invalid Image

Detail message: WorkID No image present for item. Please provide image if available.

What went wrong

The CDF file does not specify an image for this work.

What to do

While ImageUrl is optional for any given work, at least 50% of your work entries must provide a valid image through that element. Failure to do so causes the Too many invalid images error to be triggered, which causes your uploaded catalog to be rejected. If you are above the 50% threshold and do not include an image for a work, we will attempt to use an external source for the image, such as IMDb. This requires that you include enough information about the work to allow us to match it to that external source. For lack of any other image, we will provide a generic placeholder, but that is a less than ideal user experience.

Elements involved

WorkType.ImageUrl
WorkType can be Movie, TvShow, TvSeason, TvEpisode, MiniSeries, MiniSeriesEpisode, or Extra

Last updated: Dec 18, 2023