Previewing theme changes locally

Return to top
Have more questions? Submit a request


  • Victor Alekhno


    We are trying to "Starting local theme preview" and on the 3-rd step (At the prompts, enter your Zendesk Support subdomain, as well as the email and password you use to sign in to Zendesk Guide.) we face an error:

    Uploading  Failed: SSL_connect returned=1 errno=0 state=error: certificate verify failed
    C:/Ruby23-x64/lib/ruby/gems/2.3.0/gems/zendesk_apps_tools-3.7.1/lib/zendesk_apps_tools/theme.rb:45:in `rescue in full_upload': undefined method `[]' for nil:NilClass (NoMethodError)
    What can be a reason?
  • Anna Roussanova
    Zendesk Team Member

    Hi Victor, you need to enter the full URL (including the protocol), not just the subdomain. So in your case you'll need to enter

    Anna R. | Senior Technical Support Architect |
    Zendesk Experience Research Panel

  • Victor Alekhno

    Hello Anna.

    Thanks for so fast response)

    But the result is the same, even with full URL:

  • Anna Roussanova
    Zendesk Team Member

    Hi Victor, sorry, I left out an important note. The first time you enter your URL, it's saved in a hidden .zat file. I suspect that the old (invalid) URL is still getting pulled from that file. You'll need to delete the file and re-run the zat theme preview command. Check out step 3 under "Starting local theme preview" in this article.

  • BrightShadow

    The theme preview feature doesn't work stable. It is breaking connection really often. The page reload sometime breaks, sometimes is working sometimes is not - without any console errors actually.

    It is really unstable, and as a frontend developer I can't work with that in straightforward way.

    Much better solution will be to run web server locally and just serve data into Zendesk theme, why it is so complicated and all templates and so on must be uploaded to the server? 

    It is really slow and annoying when you want to work on it, spend about an hour or two to make all those things work, to install it etc. and finally you need to go back and make your hands dirty with plain js and css on your admin portal.

    BTW: it is working quite stable early morning, then probably server is overloaded and ..... you know.

  • Devan - Community Manager
    Zendesk Community Team

    Hello BrightShadow,

    Love the name. So I can see why this would be a bit problematic, so I'll be passing this on to our tech team. I would still recommend posting this in our product feedback forums so our devs and other users can add their thoughts to your use case. Let us know if we can help further, and thanks for the feedback.

    Best regards. 

  • Abdul Qabiz

    BrightShadow Many of us have noticed this issues. I think, the livereload implementation within zendesk_apps_tools is buggy. I tried to change code to fix existing implementation, it can be fixed. However, it was quicker for me to add support for an external livereload tool.

    I run zat theme without live reload; and run my own livereload to do all reloading.

    If you are interested to try what I have done, you can follow steps below. Please note I have tested it on macOS (High Sierra), and ruby, gem, bundle, and node.js is required.

    Wherever you see "code" command (launches VSCode), you can replace it with "vim", "nano", or any other editor you use. I used "code" in the instructions below becuase that's what my team uses, though I personally use "vim".


    Note: Please try following at your own risk, following comes on "AS-IS" basis. I just this solved problem quickly (not so elegantly) so I can focus on real work I do. You should never run a command in terminal unless you understand what it does; you should never run any code unless you have looked it.


    In your Terminal, and do the following after understanding what you are doing:

    1. mkdir ~/.zat-status
    2. npm install -g livereload
    3. cd ~/
    4. git clone modified_zat
    5. cd ~/modified_zat
    6. bundle
    7. gem build zendesk_apps_tools.gemspec
    8. code ~/.bash_profile #you can put in .zshrc or other places; if you use different shell
    9. Add following lines at the end of ~/.bash_profile file opened in vscode
      #Override the zat command to use binary from modified_zat directory
      alias zat="$HOME/modified_zat/bin/zat"

      #Create an alias so we can access zat theme prevew by using zatp
      alias zatp="zat theme preview --no-livereload --file-to-touch-after-upload=$HOME/.zat-status/dummy.css --use-external-livereload"

      #livereload server alias
      alias liver="livereload $HOME/.zat-status"
    10. Open new Terminal window (or run source ~/.bash_profile from existing terminal window); and run following commands:
    11. Open new Terminal tab, and run following from your project (theme) directory

    12. You can now work on theme and hopefully livereloading won’t stop.


    This is what happens:

    1. zat theme preview is run without built in livereload
    2. zat theme preview will now inject our own version of livereload.js in the code it uploads to server. Our version of livereload.js will try to connect livereload server on localhost:35729
    3. zat will touch a file a file dummy.css  in ~/.zat-status whenever you make changes in style.css or script.js of your theme.
    4. zat will touch a file dummy.css.html in ~/.zat-status whenever you make changes in templates or manifest or any part that requires zat to do full upload of the theme before livereload can happen
    5. In both of cases (#3, #4), livereload (the another tool we installed; you can use LiveReload Desktop app also to watch ~/.zat-status directory and skip using liver command above) will reload the parts of or entire page. Basically, LiveReload watches changes in .zat-status, and it reloads the page only when any html file has changed; it reloads parts (css, script) when css/javascript changes.
    6. If you use Chrome, you can use livereload extension, allow it to access ~/.zat-status directory, and then extension can reload the page itself; you don't need to run any server (livereload cli command, or LiveReload Desktop); I prefer server because I don't want to allow browsers to access my filesystem.

    If you try, and it helps you please let us know here.


    Thank you


    Abdul Qabiz

    Team Diziana


  • Matthew Bass

    We're using ZAT to edit our theme locally. We're porting HTML/CSS from our web site. This code contains a lot of SVG image definitions which makes the file long (around 1700 lines). We're getting this error:

       Uploading  Failed: the server responded with status 400

           Error  header L:: File too long.

    Why is there a limit on file length? It's going to be very difficult for us to port our existing web site theme to Zendesk if each file is limited to an arbitrary length.

  • BrightShadow

    Abdul Qabiz, perfect. That's brilliant. I didn't even think about that this could be a problem with live-reload only. I got also problems with the zat theme preview command at all. Sometimes is stops watching files.

    I will try to disable live-reload at all, that's easy. I'm using a chain of npm / SCSS etc to work on theme. So I use gulp stack that is building dist folder which is observed by the ZAT. Maybe that could be a problem also...


    Anyway, thanks for help Abdul. I appropriate it very much.

  • Azhar

    After providing subdomain and credential receiving following error:

    Uploading Failed: SSL_connect returned=1 errno=0 state=error: certificate verify failed.

    Can anyone help on this ?

  • Aiden Mendez

    Hi, I'm getting a server error after entering my username and password (below). I'm certain that everything I've entered is correct. I'm running zat theme preview inside the folder where my custom theme files are stored. Generating and Uploading theme appears to run correctly. I'm running a on a 2019 Macbook Air, Catalina 10.15.5. I've also tried running it with sudo and get same results.

     Uploading Failed: the server responded with status 403
    Server error.

  • Bryan - Community Manager
    Zendesk Developer Support Team

    Hi Aiden Mendez -- Has this worked before during other theme development? Or is this a new effort and has never worked for you? Since this sounds account specific and perhaps is a setup, subscription level, or a rights issue, I suggest submitting a ticket

  • Aleksey Kislov

    Aiden Mendez does by chance your password contain backslash symbol and you put it in .zat file? If yes, it should be escaped with another backslash, e.g. MyPass\123 > MyPass\\123.

    ZAT server starts going crazy and just throws obscure 403 when it sees backslashes. I'd added this in ZAT documentation though to save a couple of man-hours of debugging.

  • Aleksey Kislov

    How can I preview changes for a different brand if my Help Center has multiple brands?

  • Jonathan Brown


    For a good year now we've been using the zendesk theme preview fine to develop.

    Recently(last month?) we started getting a 403 forbidden error without us doing anything different. 

    have tried all different variations using zat theme preview
    (full url, subdomain only, email + pword, email/token etc)

    What gives?

  • Bryan - Community Manager
    Zendesk Developer Support Team

    Hi Jonathan Brown. Is it possible that your account's password access became disabled?

    Double check and see if this option is enabled or disabled:

  • Romain Miroux

    Hey, @..., Jonathan Brown

    I'm having the same issue.

    I've been using the zat theme preview since the beginning of the year without issues. Didn't used it last month and now I'm getting the "Uploading Failed: the server responded with status 403" after entering the credentials.

    I've checked the Password Access option and it's Enabled.

    Thank you.


  • Augusto Silva
    Zendesk Team Member

    Hi Jonathan Brown, Romain Miroux,

    We've identified the problem that is blocking you from previewing the theme locally and expect this problem to be fixed soon.

    I'll provide an update here when the issue has been addressed.

  • Kevin Gil

    Augusto Silva I am also experiencing this issue. adding a comment so I can be updated as well.

  • Jonathan Brown

    Just an FYI from my ticket with zendesk incase this helps anyone else.

    The dev team looked into it :

    "They've had a look into your case and this is what they found. Somewhere within your script, they are noticing that it is triggering the 100125 WAF Cloudflare rule hence why it never reached us because it was dropped at Cloudflare's side."

    Cloudfares documentation on this error refers to it as:

    "Block AngularJS Sandbox attacks"


    Interestingly this only happens previewing locally and not if we upload the theme to either sandbox or production environments. 


    For my particular instance I discovered it had a problem with a piece of Javascript we were adding in to add New Relic tracking. so now we just add that in at build time rather than previewing.


    hope this helps. 

  • Augusto Silva
    Zendesk Team Member

    Hi all,

    As Jonathan Brown mentioned, we found that the root-cause was a WAF rule that was too strict.

    The rule has been adjusted so you should not find this issue anymore.

    Please let us know if that's not the case.

  • Hugo Baeta

    I'm echoing some comments I've seen in this thread. I just configured this a few days ago, it was working fine. Yesterday, when I tried to use `zat preview theme`, after authenticating, I get this error:

    Failed: the server responded with status 403

    I've made sure all the API configurations are correct, I'm using an API token to authenticate (since we use Google Login). Any ideas how to get this fixed?


  • Bryan - Community Manager
    Zendesk Developer Support Team

    Hi Hugo Baeta. You mention that you're using an API token. Are you using the format for the user's login ID? Then the token for the password?

  • Hugo Baeta

    ha! that `/token` at the end of the login email did it!

    Thanks Bryan!

  • Bryan - Community Manager
    Zendesk Developer Support Team

    Great to hear Hugo! Thanks for confirming :-)

  • Jeremy Heath


    I need to update my API to v2 but I am not a coder or Html anything..

    So i started reading in to how to do it.

    I have made the change to the file so it should be done but I need to test it. I'm guessing before I upload it again. Which makes sense.


    But I have just been reading the instructions for ZAT etc, omg.

    Never mind the Linux and the codes etc.


    Is there not a simple way I can view these files without all that stuff? Something that doesn't need all this techy stuff?

    All im doing is changing a 1 to a 2..

  • Gorka Cardona-Lauridsen
    Zendesk Product Manager

    Hi Jeremy Heath

    You can change the version number in the manifest.json file without using ZAT, but ZAT makes it easier to preview changes and validate that the theme code conforms to the them requirements.

    Here's how you can do it:

    1. Download the theme
    2. Unzip it
    3. Open the manifest.json file with any basic text editor or code editor. Sublime text 3 is a good one, but just about any including OS build in text editors will make due.
    4. Change the "api_version" value to  "2". Here's how it should look.
    5. Save the file and Zip/compress the folder that contains all the theme files.
    6. Upload the theme

    If your theme did not use any of the deprecated helpers or properties you should be good to go, but if it does, you will receive a list of errors when you upload the Zip that will look something like this:


    Each error tells your what the errors is and in which file and line in the file the error is.

    Then you find each file with an error in your unzipped theme, open the file with your text editor and make the changes described here to the corresponding helper/error. Some can just be removed as they where not rendering anything anyway and some should be changed. 

  • Bryan - Community Manager
    Zendesk Developer Support Team

    Jeremy Heath, along with what Gorka mentioned, keep in mind that upgrading to v2 templating is optional. As mentioned in Gorka's article Announcing Guide Templating API v2:

    "We have not yet deprecated v1 of the Templating API, however most new theming features will be released for the Templating API v2 only going forward"

    You mention "All im doing is changing a 1 to a 2" — if that's the case and you're not taking advantage of anything in v2, you could probably just leave things alone for now. Just a thought.

  • Jeremy Heath

    Ok that helps thanks.

    Yes I have 16 errors

    I downloded notepad++ so I can see the line numbers 

    I have reduced the errors to 9 by doing the simple ones. 
    The remaining ones don't seem to have a replace with this text sort of option.

    Here is the list

    message:'article_results' does not exist

    message:'article_results' does not exist

    message:'post_results' does not exist

    message:'post_results' does not exist

    message:'internal' does not exist

    message:not possible to access `internal` in `section.internal`

    message:'user_info' does not exist

    message:'internal' does not exist

    message:'internal' does not exist


  • Bryan - Community Manager
    Zendesk Developer Support Team

    The objects mentioned — article_results, post_results, etc — these are version 1 template helpers that have been removed in version 2.

    See Upgrading from Templating API v1.

    When switching to "v2", you are committing to updating/rewriting your Help Center templates to conform to version 2 template features.

    If you are not planning on taking advantage of any v2 features, staying on v1 shouldn't be an issue. Is there a particular feature that is causing the need for the upgrade? If so, you will need to modify these templates to  use only version 2 template helpers.


Please sign in to leave a comment.

Powered by Zendesk