Troubleshooting Cards

Troubleshooting Guide

Use this troubleshooting guide to help to identify and resolve commonly encountered issues during Cards development.

If you are unable to find the solution to an issue here, please use the Twitter Cards category on the developer forums.

 

Checking your site's SSL configuration

Twitter's web crawler requires the use of TLS v1.1 or greater. You should also confirm that other aspects of your site's SSL configuration are correct, using a service such as Qualys SSL Labs.

Incorrect configuration may prevent Twitter's web crawler from accessing your site.

 

Validating Twitterbot

Twitterbot is the User-Agent that Twitter uses when crawling URLs shared on the platform (with version, such as Twitterbot/1.0). You can verify that the traffic coming from a Twitterbot User Agent is legitimate using two different methods:

  1. IP Address Range and ASNUM

    Twitter’s aggregate outbound IP ranges are 199.16.156.0/22, 199.59.148.0/22 and 192.133.76.0/22. Twitter’s ASNUM is AS13414.

    If you are receiving traffic from Twitterbot that is coming from an IP in these ranges, it is legitimate. Otherwise, it is someone posing as Twitterbot. The ranges listed here are kept up-to-date if they were to ever change.

  2. Command line tools

    First, run a reverse DNS lookup on an IP address posing as Twitterbot, using the host command.

    $ host 199.59.150.180 

    180.150.59.199.in-addr.arpa domain name pointer r-199-59-150-180.twttr.com.

    You should see the domain name is either twitter.com or twttr.com.

    Next, run a forward DNS lookup on the domain name from the first step, again using host.

    $ host r-199-59-150-180.twttr.com 

    r-199-59-150-180.twttr.com has address 199.59.150.180

    You should see that the IP address that is returned is the original one labelled as Twitterbot from above. This means this IP address is actually coming from Twitter.

     

Card Validator

I get the message, “ERROR: Fetching the page failed because the request timed out.”

These are some possible explanations:

  • Your site is configured to block web crawlers.
    If you are using WordPress, Blogger or another hosted CMS provider, your settings may inadvertently blocking crawler access from Twitter servers. You can read our CMS integration page to see how to enable web crawler access to your CMS site.
  • Your website has a robots.txt file that is blocking Twitter from getting your Card metadata.
    To learn how to diagnose this case, click here.
  • Your Apache .htaccess file is denying requests.
    You can check this by opening your .htaccess file and looking for something like the following:
    deny from 199.59.156.*
    Be sure to remove any deny directives from your .htaccess file.
  • An image is too large for the web crawler to download.
    The web crawler will typically download up to 5MB images. If you are seeing this issue, you may want to scale down the size of the image significantly and try again.
  • A network lag is causing a delay in fetching your site or images.
    If your server is in a remote location, or has unreliable network access, the web crawler may have difficulty downloading your meta tags or images. Please retry as necessary.
  • Your web host may be blocking web crawler access to your site.
    You should contact your hosting provider and ask them to ensure they are not blocking Twitter access by either IP or ASNUM. You can learn more about verifying Twitterbot above.
     

I get the message, "Failed to get a proxied URL for the image" (or an image is not shown)

The most common cause is that the image specified via the twitter:image tag is not 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.
 

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

These are some possible explanations:

  • The dimensions of the image are smaller than the recommended size.
    Images should be a minimum of 144 x 144 pixels in size.
  • A network lag is causing a delay in fetching your images.
    If your server is in a remote location, or has unreliable network access, the web crawler may have difficulty downloading your images. Please retry as necessary.
     

I get the message, "Caught Exception in App Proxy Service..."

The most common cause is that the ID specified for the twitter:app:id.* tag is prefixed with “id”. Try removing the prefix (so it only has an integer value) and re-submitting to the validator.
 

I get the message, “Invalid card type.”

The most common cause is that the page is missing a content-type meta directive. It might look something like the following

<meta content="text/html; charset=UTF-8" name="Content-Type" />


I get the message, "ERROR: Fetching the page failed because the response is too large."

Twitter's crawler has a limit of 2 MB for page responses. If you are seeing this issue, you should try reducing the size of the HTML response so that it is below the limit.
 

The validator cannot reach my testing or staging environment.

Many testing or staging environments run under restricted access. As a result, the card validator cannot access these servers to read the 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.
    Twitter uses the User-Agent of Twitterbot (with version, such as Twitterbot/1.0), which can be used to create an exception in your robots.txt file.
        User-agent:Twitterbot
    Disallow:

 

Card Display Issues

My Tweet is missing the image/video/summary text.

These are some possible explanations:

  • Your website has a robots.txt file that is blocking the crawler 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 Card does not appear in the timeline.

Twitter Cards generated from developer meta tags only appear when a Tweet is either expanded in the timeline (on web) or viewed on the Tweet’s individual permalink page (by clicking on the date from the timeline, either on web or on mobile).

In limited circumstances, Cards may appear in the timeline, such as in images posted to Twitter, Ad formats and Twitter-run experiments.

If you are looking to bring media (photos, videos and Cards) into the timeline, please consider one of the following options:

  • Accounts can pin a Tweet to the top of their timeline, which auto-expands the Tweet and displays the Card (this is possible on web only).
  • For photos, animated GIFs and videos, upload the media directly with the Tweet or consider using the Twitter API to upload media.
  • For Ad formats with a call-to-action, visit Twitter Ads for Lead Generation and Website Cards.
     

My Tweet shows an outdated version of my Card.

Once your domain is known to the validator, the web crawler re-indexes the meta information on your tag roughly every seven days.

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

 

Refreshing a Card in a Tweet

I updated my site meta tags, but my Tweet shows the old Card. How do I refresh the Card?

The Twitter web crawler re-indexes the Card tag information on your page roughly every seven days.

When testing and/or iterating on Cards, it is sometimes helpful to test updates on your timeline. It may be possible to use the following technique to refresh the cache with your most up-to-date changes of your page's Card.

  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
     

Additionally, you can create multiple bit.ly URLs to allow for repeat testing. For example, adding placeholder value 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.

 

My Card information now refreshes, but images are not updating. How do I get the images to refresh?

Images referenced in a Card are also cached based on URL. This often causes images to not update when the above Card refresh technique is used.

To work-around this issue, you can add an extra parameter at the end of your image URL so that the Twitterbot treats the image as a unique URL and re-fetches the image.

For example:

<meta name="twitter:image" content="http://example.com/myimage.jpg?4362984378"></meta>

 

Debugging Player Cards

How do I test my Player Card?

For the web, 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 plays directly in a browser (before testing in the Twitter timeline).

In general, the twitter:player tag should have values that can play directly in a browser. (If they do not, 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 tag
  5. Paste that into the address bar of your browser
     

My video is not 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 are not specified.
    Be sure to include the twitter:player:height and twitter:player:width tags with your Card tag.
  • The video format is not supported.
     

Debugging App Cards

For App Cards or App Deep Link code, users often see that the Card fails to render when posted in a Tweet. Here are some possible reasons and solutions.

  • The URL with the Card has not been validated via the Validator.
    Be sure to validate your Card here.
  • The image you uploaded to the App Store is larger than 5MB.
    This will prevent the validator from properly validating your Card. Once validated, it will also prevent your Tweet from rendering a Card. You will need to upload a smaller image to Apple (and possibly re-submit your app to the App Store for approval).