Preview has built incorrectly

A Preview says it is “ready”, but shows a blank page

When a Preview says it is “ready”, that means that it successfully ran the commands in your configuration file, and none of those commands returned an error. It does not necessarily mean that those commands did what you expected them to do. For example, your configuration might set up a database, but not provide the correct password to some application config file. In this case, the Preview would build successfully, but the application might not load.

To troubleshoot where this might have gone wrong:

Double-check the commands in the configuration file.
Check the Preview’s logs for any clues, and.
Make use of Tugboat’s terminal access to the Preview to do the same type of troubleshooting you would do if this happened on your local installation.

A Preview is pulling the wrong Docker image

Have you updated the Docker image you want your Preview to use, but it still appears to be pulling the old image? There are a couple of things that could be in play here:

Verify what version of the image you’re calling

Maybe you thought you had left a version tag off, so you’d be getting the latest Docker image, but you had actually called a specific version of the image in the config file. (Or vice versa! Maybe your config file calls latest or doesn’t specify a version, but you actually need a specific image version.) First thing’s first; double-check whether you’re calling a specific version of the Docker image in your config file, and update as necessary.

Rebuild the Preview from scratch

The more common issue is performing a Preview Action that doesn’t actually call the Docker image specified in your config file.

If you’re building a Preview from a PR, and you’ve got a Base Preview set in your Tugboat project, the Preview from your PR only executes commands in the build portion of the config file. Your Docker image is pulled before init.

For more info, see: When does Tugboat pull a Docker image, and When does Tugboat update a Docker image?

Basically, this means building a Preview from a PR when you’re using a Base Preview will never pull a new Docker image.

The practical fix for this issue is to build the Preview from scratch, without using the Base Preview. If you want to change the Docker image in your Base Preview, so all new Previews will build from the new image, you’ll need to Rebuild the Base Preview.

Tip

If you’re using the Repository Setting to Refresh Base Previews Automatically, this does not update the Docker images used in your Preview. This only kicks off a Refresh, which runs config file commands from both update and build. You need to manually Rebuild a Base Preview to pull a new Docker image.

Using Base Previews - unexpected Preview build results

When you’re using Base Previews, you may experience a few different types of unexpected build results:

A Preview that I didn’t expect has built

When you build Previews after building a Base Preview, those Previews generate new Preview builds from every Base Preview type that matches against the new Preview build. If you’re seeing a build that you didn’t expect, view your Base Preview types and verify they’re set for the appropriate Base Preview Type.

One example might be that you have two Previews set as Base Previews: a Repository Base Preview and a Branch Base Preview. When building a Preview that matches against the Branch, you’ll actually get two Preview builds: one for the Repository Base Preview, and one for the Branch Base Preview, since both match the new Preview build. You can change the Base Preview Type - for example, stop using a Repository Base Preview, or change the Base Preview Type to Branch Base Preview - if you don’t want every new Preview to build from both Base Previews.

A Preview that I expected to build is missing

If you expected to see a Preview build that you don’t see, there are a few different things to check:

Automatically building Previews from Pull Requests

In the Preview Won’t Build section, we cover Previews are not building automatically; this same thing applies when you’re using Base Previews. Go into Repository Settings and make sure the repository you’re building Previews from is set up to Build Pull Requests Automatically.

Setting Base Previews

The next thing to check is whether the Base Preview you expected to see as the basis for the missing Preview build is set as a Base Preview.

Go to View Base Previews and confirm that the Base Preview you expect to see is listed there.
If not, you’ll need to set the Preview that you want to use as your Base Preview. Then, all new Preview builds that match the Base Preview Type you specified will build from that Base Preview.

Matching against Base Preview Types

Finally, verify that the Base Previews you’re using are set to the appropriate Base Preview Types. If you’re not seeing a Preview built from a Base Preview that you expect to see, that Base Preview might not be set for the expected Base Preview Type.

One example might be that you have a Base Preview set as a Branch Base Preview instead of a Repository Base Preview, and the pull request you’re building the Preview from doesn’t merge into that branch. In this case, you’d need to change the Base Preview Type to Repository, to ensure that all Previews built in this repository build from the Base Preview, or manually build the Preview from the specific Base Preview you want to use.

Go to View Base Preview Types and confirm that the Base Preview is set for the appropriate Base Preview Type.
If necessary, change the Base Preview Type to produce the expected build results.
Alternately, if you don’t want to change a Base Preview Type, you can manually create a Preview build from a specific Base Preview.

Something in my Preview isn’t right

It’s possible for a Preview to build, but to be missing something you expect to see. This is similar to the “Preview says it is “ready”, but shows a blank page” issue above; your Preview may not have failed during the build process, but it’s possible something in the configuration file didn’t execute as you expected.

To troubleshoot where this might have gone wrong:

Double-check the commands in the configuration file.
Check the Preview’s logs for any clues.
Make use of Tugboat’s terminal access to the Preview to do the same type of troubleshooting you would do if this happened on your local installation.

If you can’t figure out why something isn’t as you expect in your Preview, let us know! Visit us at Help and Support; we’re happy to help.

Tip

If you’re using the online, start, or clone service commands to run additional commands after a Preview has built, and you’re not getting the expected result, you may be running into a caveat about the conditions under which the commands run. Take a look at service commands to run after Preview build, and feel free to reach out at Help and Support if you can’t figure out which command is problematic.

Troubleshooting Visual Diffs

Visual diffs aren’t displaying, or aren’t displaying as I expect

To configure which pages have visual diffs generated, you need to specify the relative URLs of the pages in a visualdiffs key in the Service definition. That information should be in the config file of the branch or PR that you’re building, not the Base Preview.

Some things you might try when troubleshooting a visual diff include:

Confirm the relative URL is correct;
Consider overriding the default timeout option;
Consider overriding the default WaitUntil option.

Overriding the default timeout option

services:
  apache:
    visualdiffs:
      # Create a visualdiff of /blog, but override the default timeout option
      - url: /blog
        timeout: 10

Overriding the default waitUntil option

services:
  apache:
    visualdiffs:
      # Create a visualdiff of /about, but override the default waitUntil option
      - url: /about
        waitUntil: domcontentloaded

If you’ve verified the relative URLs are correct, and that information is in the config file of the branch or PR you’re building, but you’re still not seeing what you expect to see, reach out to us at help and support - we’re happy to take a look!

URL not found

If the URL you use when configuring your visual diffs doesn’t match a relative URL in your site, you may see visual diff panes generate, but with “Not Found” message inside the images. If this happens, edit your config file to specify the relative URLs of the pages you want to diff, and then Rebuild the Preview.

There was a problem generating Visual Diffs for this preview.

If there’s an issue with the way your visual diffs key is configured, you may get the “There was a problem generating Visual Diffs for this preview” error. This could be because of the relative URLs in your config file, or it could be that you need to override the default timeout option or the default waitUntil option. If you’ve tried those things, and are still having problems, reach out to us at help and support - we’re happy to take a look!