Previewing theme changes locally

Return to top
Have more questions? Submit a request


  • Ben

    Just wanted to reach out here to see if anyone has been running into issues with the ZAT when trying to work on themes locally. For some reason it's not picking up changes to template files any more and I have to close down and rerun zat theme preview for every change. 

    One of my team also is getting intermittent issues where it's taking ages to fully spin up with web server which is doubly annoying given the above. 

  • Elisabeth Wetchy

    Hello all, great feature! Just mentioning that for me on Windows 10 it works best with --no-livereload as well, without that flag the style seems to disappear once the page is reloaded.

    I'm also noticing that some of the $assets references in my style.css seem to be resolved correctly while others arent - for example something like background-image: url("$assets-foundry_logo-svg"); works fine, but referencing our fonts like so doesn't work:

    @font-face {
    font-family: "Avenir";
    src: url("$assets-avenirnext-regular-08-ttf");
    font-weight: 300;
    font-style: normal; }

    and gives me the following error:

    GET http://localhost:4567/guide/$assets-avenirnext-regular-08-ttf net::ERR_ABORTED 404 (Not Found)

    Is this a known issue?

  • Dan Ross
    Community Moderator

    When developing locally, you're serving from the filesystem, by default that will be without HTTPS, as no SSL certificates will exist. 

    This error should be showing when doing local development. 

    When you upload your theme to Zendesk Guide, the resources will be hosted under HTTPS (assuming you have an SSL certificate), and you should no longer get those errors. 


  • 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


  • Trapta
    Community Moderator


    Is anybody else here facing issue with zat theme preview recently? I am running zat theme preview and every time it is throwing parsing error:

    Can anybody tell why it is throwing this error? I have tried using it in two different accounts other than mine too but with no luck.


  • 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:

  • Emily Coleman

    Hello folks! I'm running into an issue where I can't get the server to even start running. I have nothing else running on the same port, and I've got root-level permissions on this machine, so I'm not sure the issue.

    Here's the error:

    /Library/Ruby/Gems/2.3.0/gems/eventmachine-1.2.5/lib/eventmachine.rb:530:in `start_tcp_server': no acceptor (port is in use or requires root privileges) (RuntimeError)

    (this sets off a slew of other errors, but this seems to be the cause).

    I've tried manually setting a different port (with something like zat theme preview -p --port=9200), but I still hit the same error. I've done some googling, but all of the suggestions are coming up useless. 

    Any advice would be greatly appreciated!

  • Eduardo Alberto

    @trapta, were you ever able to fix this? I keep losing connection to the socket on every code change.

  • Anna Roussanova
    Zendesk team member

    Hey Keanan and Ursula,

    That error is coming up because the manifest.json file in your theme is either missing the "settings" parameter, or that parameter is empty. Can you double-check that file and make sure you didn't accidentally delete all the settings from there?

  • Diziana

    Awesome! Much awaited feature. Thank you.

  • 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.

  • Keanan Jones

    Hi there,

    When trying to run `zat theme preview` I am getting the following errors:

    dist $ zat theme preview
    Generating Generating theme from local files
    /Users/myusername/.asdf/installs/ruby/2.3.1/lib/ruby/gems/2.3.0/gems/zendesk_apps_tools-3.2.3/lib/zendesk_apps_tools/theming/common.rb:43:in `settings_hash': undefined method `flat_map' for nil:NilClass (NoMethodError)

    If anyone has any suggestions please could you help, thanks

  • Ursula Cedillo-Johnson

    Hey y'all! 

    I'm also hitting the same error code. This is the first time I'm using zat theme preview. I ran zat new to initialize the zat app. I don't have a zat server running. Could someone advise? 

  • Eduardo Alberto

    @Trapta Here's a screeshot: 

    I've already tried using incognito, checked if ports were being used, if extensions could be impacting, etc.

  • 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?


  • Eduardo Alberto

    Has anyone had any luck troubleshooting livereload constantly losing connection?

  • Maria McDowell

    Actually, never mind. I read more closely and realized I had misunderstood the documentation. Here is what is in my .zat file, and it works:

    "subdomain": "",
    "username": "",
    "password": "mytoken"
  • Trapta
    Community Moderator

    @Alexey Vorobyov, try hard reloading. script file gets cached resulting in showing older version of file instead of updated one with the changes.

    Let me know if this solves your issue.

    Team Diziana

  • Shammel

    How do I get rid of this warning when previewing a theme locally?

    Mixed Content: The page at '' was loaded over HTTPS, but requested an insecure stylesheet 'http://localhost:4567/guide/style.css'. This content should also be served over HTTPS.

  • 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.

  • Pasquale Errico

    I have a problem, i think, with livereload and ZAT.

    If a launch Zat Theme Preview my pages are unformatted and slowly, the console show this:

    and some others.

    I have allowed the Insecure Content on Chrome and also test with zat theme preview --no-livereload but doesn't work.

    I must work with online data, on our guide, but it seems impossibile!

    There is a work around for this problem?

    Thanks a lot

  • Ryan McGrew
    Zendesk Product Manager


    I haven't seen this error before. Have your tried restarting the ZAT preview session to see if that fixes it? You should be able to hit ctrl-c to kill the process, then type zat theme preview again and navigate to the theme preview start URL.



  • 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. 

  • Ryan McGrew
    Zendesk Product Manager

    Hmm... I'm not really sure @Trapa. It seems like something on your machine is preventing you from using that port. I haven't seen it reported it by anyone else, so it's hard to diagnose. We're using this library which doesn't have any open issues related to what you're running into -

  • Keanan Jones

    Hi Anna,

    Thanks for your response.

    I was trying to use `zat` to setup a new project locally and then ran `zat theme preview` straight after, it was failing since this was a new fresh app without any settings.

    I downloaded our current theme and ran `zat theme preview` which then worked.


  • Bryan - Community Manager
    Zendesk Developer Support

    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?

  • Augusto Silva
    Zendesk team member

    @drewbeck Did you have a look Some similar problems are discussed there.

    @Maria, Your "username" should be just "" and the password should be "my-token-from-active-api-tokens"

  • Emily Coleman

    Hey Bryan—thanks for following up!

    Unfortunately, I don't get any returns when I grep the port number—just comes back with nothing. I tried running a gem update, but no dice on that either. And sadly the restarting didn't come up with anything.

    Do you know if this might be IP address related? I've read a few things about the IP address not binding correctly (as shown in one of the answers here:, but I wasn't sure if that was entirely accurate in this use case, since the preview URL is hosted by Zendesk.

    Thanks again for looking into it!

  • Dan Ross
    Community Moderator

    Hi Ryan,

    Are there provisions going to be made for accounts that have disabled password based authentication, as this affects API auth as well. 



  • 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.


Please sign in to leave a comment.

Powered by Zendesk