Troubleshooting

I have signed the Adobe CLA twice and its check still requires signing it

Sign the Adobe CLA!

No signed agreements were found. ...

Check if you entered your GitHub username correctly.

failed: Error in connection establishment: net::ERR_CONNECTION_REFUSED

LiveReload is a tool that refreshes your browser when you run jekyll serve.

WebSocket connection to 'ws://127.0.0.1:35729/livereload' failed: Error in connection establishment: net::ERR_CONNECTION_REFUSED

Try the following in this order:

1. From your terminal, enter pkill -f jekyll and try again.
2. Close all your terminals, open a new one, and try again.
3. Clean your browser cache and try again.
4. Quit and restart your browser and try again.
5. Reboot your machine and try again.

If you’ll still encounter the issue, disable the tool by adding livereload: false to your _config.local.yml.

LoadError: cannot load such file -- html-proofer

In most cases, you'll see it after cloning a new project or upgrading/changing your Ruby environment. Ruby cannot find one of its libraries (gems) required by the running application.

Full output:

~/Projects/repos/magento/merchdocs (master *)$ rake
rake aborted!
LoadError: cannot load such file -- html-proofer
/Users/bjones/Projects/repos/magento/merchdocs/Rakefile:12:in `<top (required)>'
(See full trace by running task with --trace)

Solution:

To manage all the gems, we use Bundler that helps to install them all at once.

bundle install

error: The following untracked working tree files would be overwritten by checkout

~/Projects/magento/merchdocs (update-baseurl)$ git checkout develop
error: The following untracked working tree files would be overwritten by checkout:
        src/_data/main-nav.yml
Please move or remove them before you switch branches.
Aborting

Case 1: You created new files (directories) in your working directory that have not been added (staged) and had never been committed in the past to your branch or its ancestors.

Solution: If you don't need them anymore, delete them.

Check files to be deleted:

git clean --force --dry-run

Check directories to be deleted:

git clean --force --dry-run -d

Delete all files and directories:

git clean --force -d

Case 2: You didn't create the reported file and it doesn't even exist in your directory.

Though, you can find a file with the same name but in a different letter case (upper/lower).

Possible reason: You system is set as case insensitive but git is set as case sensitive.

Solution: Change git sensitivity to resolve this particular issue.

git config core.ignorecase true
git checkout my_branch
git config core.ignorecase false

Psych::SyntaxError when running commands to preview or build the site

Psych is a YAML parser and emitter. Psych::SyntaxError points to the file with invalid YAML syntax.

(.../merchdocs/src/_data/whats-new.yml): did not find expected key while parsing a block mapping at line 5070 column 3 (Psych::SyntaxError)

YAML linter or validator can help with this.