Troubleshooting Twitter Cards

Updated on Thu, 2013-08-22 18:37

We created this troubleshooting guide to help you identify and resolve commonly encountered issues during Cards development.

Please look over the below categories to see which most resembles your issue.

We've tried to make this guide as useful and comprehensive as possible. If there's something wrong, or you feel something should be added, please reach out to us via the Twitter Cards Discussion.


Card Validator


When I validate, I get the message, "Failed to get a proxied URL for the image."

This error often looks like:



The most common cause is that the image specified via the twitter:image tag isn't publicly accessible on the web. This often happens when testing against a staging/internal-only network. To resolve, make sure your image can be accessed via the public internet.

If you want to make your private network accessible to the validator, click here to see some options.

When I validate, I get the message, "Invalid Image. This image cannot be fetched."

This error often looks like:



There are a couple possible explainations for this:

  • The dimensions of the image are smaller than the recommended size. We suggest that Product Card images (among others) are a minimum of 160 x 160 pixels in size.
  • There was a network timeout in accessing the image. Try re-submitting the request a few times to see if that helps.

As a side note, we're working to improve error messages in the Card validator. Please be patient as we make updates.


The validator can't reach my testing/staging environment.

Many developers run their testing/staging environments under restricted access. As a result, our validator can't access these servers to read the Card tags.

Below are a couple of solutions that other developers have found helpful:

  • Run your web server on a different, publicly-accessible port.
  • Configure your firewall to route port-specific requests to your test/staging environment.
  • Configure your web servers to allow Twitter access via the robots.txt file. Here's an example robots.txt: 

    1. User-agent: Twitterbot
    2. Disallow:

Cards Whitelisting


How do I get my Card approved?

We review each Card implementation to make sure it fits the guidelines for publishing to our platform. Although we strive for a quick turnaround, this process sometimes takes longer than expected.

To help make this process as smooth and quick as possible, please verify the following:

  • You've added the proper Cards mark-up to your page, and your page is publicly accessible.
  • You've tested your site through the Cards validator.
  • You've submitted your Card for approval by clicking on the "Request Approval" button.
  • If you're submitting a Player Card, the twitter:stream URL opens and plays properly in a browser.

Doing the above (as well as reading the issues throughout this page) will help make you're approval as quick as possible.



My Card hasn't been approved for whitelisting. What does that mean?

If your Card was rejected, please read through the documentation again, test your Card in our validator, and then resubmit.

The Player Card has the most guidelines, which you can read on the Player Cards Do's & Don'ts section.

For other issues not covered there, please continue reading below.



My Player Card has a mixed content/SSL issue.

To help protect the safety and security of your audience, Twitter Player Cards require that all content load securely. More concretely, you'll see this difference in the browser URL once your Card is expanded:

OK Not OK

For details on how to diagnose and resolve this type of issue, please scroll to the "Mixed Content/SSL Fix" section below.



I've re-submitted my Card for approval. What happens next?

We will review your Card and respond within three weeks. If you have problems blocking you from testing, please reach out to us via the Twitter Cards Discussion.


Cards on the Timeline


My tweet doesn't include the image/video/summary text.

There are a number of possible reasons for this. Here are some suggestions and ways to troubleshoot:

  • Your Card has yet to be whitelisted. Please run your example URL through the Card Validator, and click the Request Approval button to begin the whitelist process.
  • Your website has a robots.txt that is blocking us from getting your Card metadata. To learn how to diagnose this case, click here.
  • The video format is not supported. For steps to debug your video, click here.


My tweet shows an outdated version of my Card tag information.

Once you've been whitelisted for your domain, our web crawlers re-index the meta information on your tag roughly every week.

If you're testing and/or iterating on your Cards, it is sometimes helpful to test updates. You can follow these instructions to view updates to your Cards.



My Player Card shows summary information instead.

The most common cause of this is that you have not yet been whitelisted for approval.

Please run your example URL through the Card Validator, and click the Request Approval button to begin the whitelist process.



After approval, re-try the URL to ensure that the Player Card appears and plays properly.



My video isn't playing properly in the Player Card.

There are a number of possible reasons causing this. Here are some suggestions and ways to troubleshoot:

  • The URL specified points to a full website, not a page that fits in an IFRAME. The value for twitter:player needs to be a simplified web page with only the player on it. Having a full website will show only part of your site in the Player Card IFRAME.
  • The dimensions of the Player Card aren't specified. Be sure to include the twitter:player:height and twitter:player:width tags with your Card tag.
  • The video format is not supported. For steps to debug your video, click here.


My Player Card does not render properly on mobile.

At Twitter, we try to ensure that all content works equally across our web and mobile platforms.

To this end, we've created two tags &emdash; twitter:player and twitter:player:stream &emdash; that differ slightly in video formats and implementation.

Please read the mobile section of the Player Card page to understand how to make mobile video work for you.


Debugging Player Cards


For the web experience, Twitter relies on the user's browser to play a wide range of video formats. As a result, it is important to test that your video stream plays directly in a browser (before testing in the Twitter timeline).

In general, the both the twitter:player and the twitter:player:stream tags should have values that can play directly in a browser. (If they don't, you should consider a different video format that is widely adopted by popular browsers).

To test the video content directly, try the following in Google Chrome:

  1. Open up a browser window
  2. Enter the URL containing your Twitter Cards tags into the address bar
  3. View the source of the page (Find this in the toolbar under View->Source or View->Developer->View Source)
  4. Find and copy the URL specified in the twitter:player and/or twitter:player:stream tag
  5. Paste that into the address of your browser

Mixed Content/SSL Issue


Twitter's policy around mixed content and ssl security is intended to help protect the safety and security of your audience. (Moreover, planned releases of Firefox and other browsers will deprecate this behavior, causing content to not appear at all.)

To briefly re-state the policy:

Do not: Generate mixed content browser warnings when the video or audio player loads or if the integration automatically plays content. All Twitter clients use HTTPS, and you must not break the lock of the browser. Passive mixed content warnings are only acceptable after clicking a ¿play¿ button on click-to-play experiences.

To that end, below is an example of how to diagnose the mixed content/SSL issue. When a Player Card is expanded as such:



The browser address bar either maintains the "secure" state (left) or goes into the "insecure" state (right).

OK Not OK

Below are the steps to reproduce in Google Chrome.

  1. Open a browser window and type in the Twitter URL with the mixed-content tweet
  2. Note that the browser address has the "lock" icon to indicate a secure browsing environment
  3. In the toolbar, click on View->Developer->Developer Tools
  4. In the below pane, click on the Network tab.
  5. Under the tweet, click on the "View Media" link to expand the Twitter Card
  6. If the "lock" icon is intact, you've maintained a secure browsing environment
  7. If the "lock" icon is replaced with an "unlocked icon", the mixed-content/SSL issue is present
    1. In the Network pane, click on the warning icon () to show script load warnings.
    2. In the Network pane, look for scripts or content that shows a warning icon with the message XXX
    3. These scripts are breaching the security of the Card, and need to be turned to HTTPS

For reference, below is an image of an HTTPS error appearing in the Developer Tools -> Network tab.



In many cases, you can work with your video content provider (BrightCove, Ooyala, etc.) to resolve these issues. Please contact them first to see how they can re-configure your content.


Refreshing a Card in a Tweet

Our web crawlers re-index the Card tag information on your page roughly every week.

If you're testing and/or iterating on your Cards, it is sometimes helpful to test updates on your timeline. You can follow the below instructions to view updates to your Cards.

  1. Add Card metadata to a page
  2. Tweet URL to that page
  3. Refresh your browser to view the Card contents on your timeline
  4. Change Card metadata on the page
  5. Take the same URL and runs it through bit.ly
  6. Tweet the new bit.ly URL
  7. Refresh your browser to view the updates

      8. Additionally, you can create multiple bit.ly URLs to allow for repeat testing. For example, adding dummy parameters to the end of your URL (http://www.test.com/?x=test1) or a unique hash (http://www.test.com/#test1) will generally not affect the page contents, but will generate a unique bit.ly URL for each unique value of x.