> ## Documentation Index
> Fetch the complete documentation index at: https://samltd-6c86be8d.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting Common TMDB Errors and Problems

> Fix common TMDB problems: invalid API key errors, blank pages, images not loading, search returning no results, and browser issues.

Most problems with the TMDB app fall into a small number of categories: configuration issues (especially around API keys), network or performance hiccups, browser compatibility quirks, and gaps in the underlying TMDB database. The sections below walk through the most common issues and how to resolve them. Start with the issue that matches what you're seeing, follow the steps, and check whether the problem clears up before moving on.

<AccordionGroup>
  <Accordion title="&#x22;Invalid API Key&#x22; error">
    <Warning>
      An invalid API key will block all data from loading. Every request to the TMDB API requires a valid key, so this error affects the entire app — not just one page or feature.
    </Warning>

    This error means the API key being sent to TMDB is missing, malformed, or has been revoked. Here's how to diagnose and fix it:

    <Steps>
      <Step title="Confirm your API key exists">
        Log in to [themoviedb.org](https://www.themoviedb.org/), go to **Settings → API**, and copy your API key (v3 auth). Make sure you're copying the key itself, not the Read Access Token (v4), unless the app is configured to use the v4 token.
      </Step>

      <Step title="Check your environment variable">
        The app reads the TMDB API key from the `REACT_APP_TMDB_API_KEY` environment variable. Verify that variable is set in your `.env` file with no extra spaces, quotes around the value, or accidental line-break characters.
      </Step>

      <Step title="Restart the development server">
        Environment variables are read at startup. If you added or changed the variable while the server was running, stop it and restart it. Changes to `.env` files are not hot-reloaded.
      </Step>

      <Step title="Verify the key is active">
        On the TMDB API settings page, confirm the key shows a status of **Active**. If it was recently created, it may take a few minutes to become usable. If it shows as revoked or suspended, you'll need to request a new key.
      </Step>
    </Steps>

    If the key looks correct and the server has been restarted, try making a direct API request in your browser: `https://api.themoviedb.org/3/movie/popular?api_key=YOUR_KEY`. If that returns data, the key is valid and the issue is in how the app is reading the variable.
  </Accordion>

  <Accordion title="Content not loading / blank pages">
    If pages are blank or content is missing, try these steps:

    <Steps>
      <Step title="Check your API key">
        A missing or invalid API key is the most common cause of blank pages. Verify your key is set correctly in your configuration — see the [API key setup](/configuration/api-key) page for details.
      </Step>

      <Step title="Check your internet connection">
        The app fetches all data live from The Movie Database. A dropped or unstable connection will prevent content from loading. Try refreshing the page once your connection is stable.
      </Step>

      <Step title="Check TMDB's status">
        Visit [status.themoviedb.org](https://status.themoviedb.org) to see if TMDB's API is experiencing an outage or degraded performance. If there's an active incident, the app will recover automatically once TMDB resolves it.
      </Step>

      <Step title="Hard refresh the page">
        Press **Ctrl+Shift+R** (Windows/Linux) or **Cmd+Shift+R** (Mac) to force a full reload that bypasses your browser's cache.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Images (posters/backdrops) not displaying">
    When movie posters or backdrop images don't appear, try the following:

    * **Check your internet connection.** Images are loaded directly from The Movie Database's image servers. A slow or interrupted connection can prevent them from loading.
    * **Hard refresh the page.** Press **Ctrl+Shift+R** (Windows/Linux) or **Cmd+Shift+R** (Mac) to reload without using cached assets.
    * **Check TMDB's status.** If images are missing across all titles at the same time, TMDB's image servers may be experiencing issues. Visit [status.themoviedb.org](https://status.themoviedb.org) to confirm.
    * **Some titles have no artwork.** Not every movie or show has an official poster or backdrop in the TMDB database. If a title is obscure or was recently added, artwork may not yet be available — this is expected behavior.
  </Accordion>

  <Accordion title="Search returning no results">
    If search returns nothing when you'd expect results, try the following:

    * **Check your spelling.** The TMDB search is relatively tolerant of minor typos, but significant misspellings may return no results. Try alternate spellings or the original-language title.
    * **Try the original title.** Some international films are indexed under their original title rather than a localized translation. Searching the original title often surfaces results that a translated title won't.
    * **Remove special characters.** Ampersands, colons, and other punctuation in titles can sometimes affect results. Try searching just a few distinctive words from the title.
    * **Filter by the right content type.** Use the **Movies**, **TV Shows**, and **People** tabs on the results page to make sure you're looking in the right category.

    <Info>If you're certain a title exists and search still returns nothing, it's possible the title isn't in the TMDB database yet. See the "Missing movies or TV shows" section below.</Info>
  </Accordion>

  <Accordion title="App shows outdated information">
    If you're seeing stale data — an old poster, an incorrect release date, or a missing cast member — there are a few possible explanations:

    * **Cached response.** Your browser may have cached an older version of the page. Try a hard refresh (**Ctrl+Shift+R** on Windows/Linux, **Cmd+Shift+R** on Mac) to bypass the cache and fetch the latest data.
    * **TMDB hasn't been updated yet.** TMDB's data is community-maintained, so corrections depend on contributors submitting them. If you spot incorrect information, you can edit it directly on [themoviedb.org](https://www.themoviedb.org/).

    <Tip>For newly released titles, TMDB data often improves significantly in the days after release as contributors add trailers, images, and full cast details. Check back after a few days if a new title looks incomplete.</Tip>
  </Accordion>

  <Accordion title="Slow performance or timeout errors">
    Slow load times or timeout errors are usually caused by your network connection or a temporary issue on TMDB's end.

    * **Check TMDB's status.** Visit [status.themoviedb.org](https://status.themoviedb.org) to see if there are any active incidents or degraded performance affecting the API.
    * **Check your connection.** The app loads all data and images in real time from The Movie Database. A slow or unstable internet connection will directly impact load speed.
    * **Reload the page.** Temporary network hiccups can cause single requests to time out. A simple page reload often resolves one-off timeout errors.
    * **Try again later.** If TMDB is experiencing high traffic or a partial outage, load times may be temporarily elevated. The app will recover once conditions normalize.
  </Accordion>

  <Accordion title="App not working in a specific browser">
    If the app works in one browser but not another, try the following:

    * **Update your browser.** TMDB works best in current versions of Chrome, Firefox, Safari, and Edge. Make sure you're running an up-to-date release — older browser versions may not support all features the app uses.
    * **Disable browser extensions.** Ad blockers, privacy extensions, and script blockers can interfere with how the app loads content from The Movie Database. Try opening the app in a private or incognito window (which disables most extensions) to see if the problem disappears.
    * **Try a different browser.** If a specific browser consistently fails, try Chrome or Firefox as a baseline to confirm the app itself is working correctly. If it works in another browser, the issue is likely an extension or setting in the failing browser.
  </Accordion>

  <Accordion title="Missing movies or TV shows">
    If you search for a title and it simply doesn't appear anywhere in the app, it likely isn't in the TMDB database yet — or it was added very recently and hasn't propagated through the API cache.

    TMDB relies on its community to add new content. Indie films, limited-release titles, older catalog content from certain regions, and very recent releases are sometimes missing or incomplete.

    To add or request a missing title:

    1. Create a free account at [themoviedb.org](https://www.themoviedb.org/) if you don't already have one.
    2. Use the **Add Movie** or **Add TV Show** option to submit the new entry.
    3. Fill in as many fields as you can — title, release year, overview, and at least one image.
    4. Submit the entry and wait for it to be reviewed and approved (usually within a few hours to a day).

    Once the title is in the TMDB database, it will become searchable in the app.

    <Note>If the title is there but just hard to find, try searching by alternate titles or the original-language title. Many films are indexed under multiple names.</Note>
  </Accordion>

  <Accordion title="Incorrect or wrong information displayed">
    If the app is showing wrong information — an incorrect release date, the wrong cast, a mismatched plot description — the issue is in the underlying TMDB database, not the app itself.

    Since TMDB is community-maintained, errors do occur. The best way to fix them is to correct the data at the source:

    1. Go to the title's page on [themoviedb.org](https://www.themoviedb.org/).
    2. Click the **Edit** button (you must be logged in with a free account).
    3. Make the correction and submit it.
    4. The fix will appear in the app once TMDB's API reflects the update — typically within minutes to a few hours.

    If you believe there's a systematic or repeated error that keeps being reverted, you can flag the issue in TMDB's community forums, where moderators can investigate and lock the correct value.

    <Tip>If you notice the same error appearing across multiple titles — for example, a production company consistently misattributed — report it on the TMDB community forums rather than editing each title individually.</Tip>
  </Accordion>

  <Accordion title="Environment variable / API key not picked up after adding it">
    This is one of the most common setup issues. You've added your API key to your `.env` file, but the app is still behaving as though the key isn't there.

    <Steps>
      <Step title="Restart the dev server">
        Environment variables are read once at process startup. Simply saving the `.env` file is not enough — you must stop and restart your development server for the change to take effect.
      </Step>

      <Step title="Check the variable name">
        The variable name is case-sensitive and must be exactly `REACT_APP_TMDB_API_KEY`. Any variation in spelling or capitalization means the app won't find the value. See [API key setup](/configuration/api-key) for the correct variable name and format.
      </Step>

      <Step title="Check which .env file is being loaded">
        Make sure you're editing the `.env` file in the root of the project (next to `package.json`). If you created the file somewhere else, the app won't pick it up.
      </Step>

      <Step title="Verify the value has no extra characters">
        Open the `.env` file and confirm the value has no leading or trailing spaces, no surrounding quotes, and no accidental newline or special character after the key. A common mistake is copying a key with a trailing space that's invisible in a text editor.
      </Step>
    </Steps>

    <Warning>
      Never commit your `.env` or `.env.local` file to version control. These files contain secrets. Make sure `.env.local` is listed in your `.gitignore`.
    </Warning>
  </Accordion>
</AccordionGroup>