Previewing theme changes locally (Guide Professional and Enterprise)

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

    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

    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

    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

    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, Bryan - Community Manager, 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?



Please sign in to leave a comment.

Powered by Zendesk