Internal Documentation
Menu

Site Troubleshooting

Last updated: Sep-04-2025

Overview

This guide covers troubleshooting issues, plus Docker-specific troubleshooting for the development environment.

On this page:

Docker Issues

Problem: Docker Build Failures

Symptoms:

  • docker-compose build fails
  • Missing dependencies in container
  • Build timeouts

Solutions:

  1. Ensure Docker is running and you're logged in
  2. Clear Docker cache: bash docker system prune -a
  3. Rebuild from scratch: bash docker-compose down docker-compose build --no-cache
  4. If still not working, reinstall gem dependencies: bash docker-compose run app bundle install

Problem: Container Won't Start

Symptoms:

  • docker-compose up fails
  • Container exits immediately
  • Port conflicts

Solutions:

  1. Check for port conflicts: bash lsof -i :3000
  2. Review logs: bash docker-compose logs
  3. Reset containers: bash docker-compose down docker-compose up --force-recreate

Styled Boxes Rendering Issues

Caveats/Issues

  • List items (<li>) within a note can't start with a paragraph tag as it will add a line break. The parser will automatically do this if you include an inline html within the markdown of a list item e.g. <br>. Try and avoid this where possible, if you need a line break you can use a <p> tag.

  • There are some line spacing issues

The default texts are defined in the content renderer, in en.yml under the section "special_ui_default_titles" https://github.com/CloudinaryLtd/content_renderer/blob/master/config/locales/en.yml

Ruby and OpenSSL Issues

In Case of OpenSSL Errors on the Puma Server

Make sure to stop Puma server completely (Ctrl-C, not Ctrl-Z).

Run the following from the cld_docs folder (each one takes a few minutes). In step 2, make sure to replace <USERNAME> with your computer user name (the name that shows up before the $ in your command prompt):

  1. Install OpenSSL package: bash rvm pkg install openssl

  2. Reinstall Ruby with OpenSSL: bash rvm reinstall 2.2.5 --with-openssl-dir=/Users/<USERNAME>/.rvm/usr

  3. Bundle install: bash bundle install

GitActions CI Testing Issues

Link Checker

The link checker tool tests all the links to ensure that they're working properly and should always pass. If the link checker isn't passing for your PR, you can open the link checker report from the "Checks" section of the PR. Click the "Details" link next to the link checker test.

Once the report is open, you can use the burger menu in the top left to filter out everything except for the failing links. Once you find the failing links, they will fall into one of two categories:

  • Genuine broken link that needs to be fixed in your PR. This shows the tool is doing its job perfectly and has prevented a broken link going live.

  • An example of a URL, something else that resembles a link, or a valid link that the current link checker can't resolve (i.e. it recognizes we're a bot and blocks us). In this case, it will need to be excluded from the link checker, either by changing it or adding an exclusion to the bottom of test_utils.js.

If you need to exclude a "fake" link, do your best to use one of the already excluded URL elements if possible. For example, we already exclude all URLs containing any of the following:

To exclude a URL from the checker, add a line in the same format as the others. Try not to over-exclude - i.e if xxx.com/documentation/yyy is failing, consider excluding xxx.com/documentation and not all of xxx.com..., but don't be overly specific either.

Current Tests

  • PR test of successful deploy - if fails, blocks merge
  • Broken link checker

By default:

  • The CI-PR test only checks internal (relative) links.
  • The full deploy to production checks both internal and external. You'll get notification if your production deploy link checks passed or failed both in an email (only on failure) and in the automatic deploy message in our #doc_team slack channel.
  • Staging & nightly deploys don't check links at all.

If you want to also test external URLs during a PR test, you can commit a temporary change in .github/workflows/ci_pr.yaml - Change relative_links_only: false to true. Just be sure to revert that change afterwards before merging your branch.

Header Overflow Error

Based on Fastly request/response limits, a "Header overflow" could be returned if the request or response header count is more than 96 (though that includes internal Fastly headers and they state an actual limit of ~85) or if the response header size is more than 69KB.

If you see this error and the URL looks to be very long, force requests to avoid Fastly and instead use Akamai/Cloudflare, by using the demo-assets CNAME. In the failing URLs, replace:

https://res.cloudinary.com/demo

with

https://demo-assets.cloudinary.com/

Excluding Links

The list of exclusions can be found in the following file in the cld_docs repo: test > link_checker > src > test_util.js. Exclusions are listed in the shouldBeChecked function.

If you're adding an example, you should check the file to see if your link can be changed to match one of the existing exclusions.

If it isn't an example that can be changed to use an existing exclusion, you should add your link or a reusable pattern that will match your link to the test_utils.js file.

Once you've updated your code, you can commit and push to trigger the link checker build again and verify your fix is working.

Future Testing Ideas

  • Spellcheck - Raise warning, don't block
  • Missing Var Definition Test - looks for the "translation missing" string and fails (blocks merge) on error?

Broken Link Fixes

When restructuring content:

  • Search for all links to anchors on same page (#) and replace with links to new page as needed.

  • Find in files for links to the original page and/or anchors within the original page & fix with links to relevant new page.

Development TODO Items

Floating TOC

  • For our new design, every page should automatically have a floating TOC as long as it has one or more Hs. If not, shouldn't have a floating TOC.

  • Default title = On this page.

  • Code for that should include:

    • If there is body content before first H, then show H1 title as first title to jump back to (at same level as the rest of the H2)
    • Show all 2s and 3s indented accordingly. (Currently only shows 2's, unless the first thing on the page is a 3, then it shows that 3 + the rest of the 2s)
    • If there are no headings on the page, need to prevent showing the floating box.

Left TOC

  • Currently, you only get a "you are here" bar next to the TOC node when you're on a sub-heading within the page. When you click the node for the page itself, it should also show the bar, whether or not the page has sub-headings.

  • If a page has no sub-headings:

    • There shouldn't be an expand icon
    • It's causing problems with the TOC load - search disappears and some of the entries are hidden

Other Development Items

  • Prev-Next links - Might be better to include page title and not menu-title. [But breadcrumbs should match TOC titles]

  • Procedure steps - When a page primarily covers a process, such that the main dividers on the page are steps, would be nice to have a notation that will create a nice CSS class with a graphical number. (Something like what we've in the old HAML XXX_integration pages) - Needs design + dev markdown notation & new CSS class.

  • TOC - pointer not working to sub-pages

  • meta_suffix - If it's decided that this is a good idea (see meta_suffix description above), need to implement in en.yml.

Testing and Development

Testing Code Snippets

To test code snippets in the various SDKs you need to set up a little environment.

.NET Testing

For .NET, you can use an online tool - https://dotnetfiddle.net/#

  1. Add the CloudinaryDotNet and Newtonsoft.Json nuget packages on the left-hand side

  2. Copy the example code below

  3. Add cloudname and api key/secret

  4. Update code for your use case. Example is for an explicit transformation

VSCode Tasks

The repo has a .vscode folder which contains a tasks.json file. This file can be used to define a set of common tasks that we might want to use to simplify the authoring process. Currently we've 1 task defined, which will open a browser tab for the file that's currently open. This task can be set to a keyboard shortcut, such as CMD+o.

To define the shortcut for this:

  1. Open the keyboard shortcuts settings from the menu: Code > Preferences > Keyboard Shortcuts

  2. With this open, click the icon on the top right corner that has a page with an arrow (middle icon). This will open the keybindings.json file.

  3. In the keybindings.json file, add the following object to the list:

If you want to edit the keybinding, you can change this in the value for "key".

Development Virtual Machines and Git

Staging VM for Console

New way:

The new way means you don't have to disable the cld_doc port in order to preview the ML environment :-)

See: Install Frontend Environment

Old way:

  1. cld_docs listens to port 8443, and console listens to 8081, so need to clear listening to 8443: In cld_docs folder, clear the port listen settings: bash sudo pfctl -F all -f /etc/pf.conf

  2. In console folder, activate port listening to port 8081: bash echo "rdr pass inet proto tcp from any to any port 443 -> 127.0.0.1 port 8081" | sudo pfctl -ef -

  3. If recently merged master into doc branch, run yarn

  4. To start TAY version of console server, run yarn start:tay

Adding Application Variables for ML Capabilities

  1. Open Inspect & go to Application tab

  2. Add the new key & value. For example: cld_new_drilldown = true

Documentation Repositories

Cld_Docs Repository

https://github.com/CloudinaryLtd/cld_docs - See Readme for installation & setup.

OpenSSL Errors on Puma Server

Make sure to stop Puma server completely (Ctrl-C, not Ctrl-Z).

Run the following from the cld_docs folder (each one takes a few minutes). In step 2, make sure to replace <USERNAME> with your computer user name (the name that shows up before the $ in your command prompt):

  1. rvm pkg install openssl

  2. rvm reinstall 2.2.5 --with-openssl-dir=/Users/<USERNAME>/.rvm/usr

  3. bundle install

Content_Renderer Repository

This repository includes the code widgets, markdown renderer, and shared markdown code (used by docs, blog, cookbook, product updates, etc.).

To check which version of render the cld_docs repository is using, check the Gemfile in the root of cld_docs.

To make a change in this repository:

  1. Recommended - Before changing (esp CSS stuff) in a branch, test the planned change using inspect on the live version.

  2. Update content_renderer files as needed

  3. Test in the dummy/sample file

  4. Test in cld_docs

  5. Get a PR reviews from at least one doc member & one backend or SDK developer.

  6. Coordinate with backend dev to test the change in the cloudinary repository for impacts to the transformation widget in the console, blog posts, cookbook, etc)

  7. Deploy the new content_renderer version using Jenkins.

  8. Update the version of content_renderer that cld_docs uses to be the new version.

Testing Content_Renderer Dummy/Sample File

  1. If needed, update sample.md.html to include a sample of what you need to test.

  2. In terminal, change to content_renderer/test/dummy folder, and run: bash rails s -b 0.0.0.0 (if need bundle, connect to VPN and run bundle from your root)

  3. In browser, open http://localhost:3000/sample and check if your changes look as expected.

For changes to the content_renderer ruby code, you'll need to use the shotgun gem to be able to see changes on refresh instead of having to restart the server each time. To do this, you need to add the following code to the Gemfile and run bundle again:

Once rebundled, start the shotgun server with the following command: bash shotgun --port=3000

Test Content Renderer Changes in cld_docs

Method 1:

  1. Ensure that you have the content_renderer repository in the same parent folder as cld_docs. For most this will be <user>/dev.

  2. Checkout the branch of content_renderer you want to test.

  3. Stop the cld_docs server

  4. Uncomment the local gem line in the Gemfile in cld_docs:

(currently line 46). Then comment out the following line referencing the remote gem (currently line 47).

  1. Start the cld_docs server.

  2. To switch back to remote, undo your changes to the Gemfile, stop server, restart the server. (requires VPN)

Method 2:

  1. Stop the cld_docs server.

  2. While in the content_renderer branch you want to test, copy the content_renderer folder to the 'vendor' folder in cld_docs.

  3. Comment out the cld_url line in the Gemfile. It should look like this:

  1. Run bundle install in the root of cld_docs to install the local gem.

  2. Restart the cld_docs server (puma) and test your change.

  3. To go back to the gem stored in the gem repo, stop the cld_docs server, remove the comment from Gemfile & save, delete the content_renderer folder, run bundle install again, then re-run the cld_docs server.

Test with New Code_Generator

  1. Switch to the relevant branch of content_renderer (For PHP2 testing, the branch to test is: refactor/use-code-generator-gem)

  2. In the cld_docs Gemfile, comment out the line referencing the remote content_renderer and uncomment the line for local content_renderer

  3. Run bundle install in the root of cld_docs to install the local gems.

  4. Start the cld_docs server.

  5. To switch back to remote, undo your changes to the Gemfile, stop server, restart the server.

Media Optimizer Testing

Adding MO Cloud to Cloudinary Account

Process for adding Media Optimizer cloud environments to Cloudinary accounts for testing.

  1. In the Admin Console, increase the number of Max Customers so you have at least one account spare (remember to save)

  2. In your account settings, click add new sub-account, and fill in the details of the new account

  3. Back in the Admin console, select the cloud you just created, and save

  4. In the Flags4 list, select Media Optimizer

You should now see the Media Optimizer logo against that cloud.

Adding Images and Videos to Media Optimizer Docs

The images and videos in the MO docs are delivered through the demo-mo-docs Media Optimizer cloud (accessed through the Demo account).

Specific procedures for managing media assets in Media Optimizer documentation.

Doc Home Page Management

Changing Getting Started SVGs

The SVGs for the gradient versions are defined directly inline in the homepage.json, and then the hover version (without gradient) is handled via CSS.

To change to a new SVG:

  1. Get (only) the gradient version of both dark & light mode from the designers.

  2. Open the SVG for one of the modes in Visual Studio (or any text editor).

  3. Copy the multiline text from there to Text to One Line, to convert the SVG code to one line.

  4. Copy the single line version to JSON Escape to add the necessary escape characters.

  5. Then copy the output of that to the relevant line in the homepage.json file (iconDark or iconLight) & repeat for the SVG of the other mode.

  6. When done, you should see that the gradient SVG shows up on the page & on hover the CSS automatically converts it to the solid color.

Related topics

✔️ Feedback sent!

Rate this page: