Skip to content

Troubleshooting

Brian Duffield - Okta edited this page Jun 10, 2022 · 14 revisions

Problem: Error during yarn install: "unable to get local issuer certificate"

If you also work on the monolith, strap configures npm and yarn to use Okta's CA signing certificate. To temporarily disable this, rename ~/.npmrc and ~/.yarnrc before trying yarn install again.

Problem: Your PR has unrelated changes

This most often happens if you branch off of one branch, but then create a PR into a different branch. For example, you branch off of master but then target your PR at a release-20xx.x.x branch. It happens because master and the release branch have different commits in them.

To fix this, you will rebase the release branch against master, and then rebase your branch against the release branch.

  1. git fetch origin
  2. git checkout master
  3. git pull
  4. git checkout release-20xx.x.x
  5. git pull
  6. git rebase origin/master
  7. git checkout your-branch
  8. git pull
  9. git rebase origin/release-20xx.x.x
  10. git push --force-with-lease

Problem: You merged your PR, but it isn't showing live

Sometimes Bacon doesn't pick up a commit (SHA), and you need to create a manual commit to help it along:

  1. In your PR, locate the final commit that merged your PR to the master branch. There are a number of ways to obtain that commit ID. The following is just one way:

    • On the Conversation tab of your PR, near the bottom there is a line that states something like:
      "Your-git-hub-user-name-okta" merged commit 1k303dd into master 45 minutes ago. This is the commit that resulted in the PR's merge.
    • Click the commit ID link.
    • On the page that appears, near the top, the full commit ID appears. Copy this number. This is the value to include for SHA when you complete the manual commit in Bacon.
  2. In Bacon, click the Self Service dropdown, and then click Insert Missing Commit.

  3. In the dialog that appears, fill in the following:

    • SHA - The commit ID, for example: 4a403dc2b5b51869544b013c40ae0a84bd53a388
    • Repo - okta-developer-docs
    • Branch - The location that the commit belongs, which is master
    • Org - okta
  4. Click Insert.

Windows platform issues

If you are on a Microsoft Windows platform, you might experience the following issues.

EOL Error

Because Windows handles line endings differently than *nix operating systems, you may see the following error after running yarn dev:

yarn run v1.22.4
$ yarn workspace @okta/vuepress-site dev
$ yarn conductor:validate && vuepress dev .
$ node .vuepress/scripts/yml-parse-check.js
conductor.yml parse successful
conductor.yml exports correct values
Error: Error: conductor.yml must end in a new (but not blank) line
    at Object.<anonymous> (C:\src\repos\okta-developer-docs\packages\@okta\vuepress-site\.vuepress\scripts\yml-parse-ch
eck.js:68:11)
    at Module._compile (internal/modules/cjs/loader.js:1133:30)
    at Object.Module._extensions..js (internal/modules/cjs/loader.js:1153:10)
    at Module.load (internal/modules/cjs/loader.js:977:32)
    at Function.Module._load (internal/modules/cjs/loader.js:877:14)
    at Function.executeUserEntryPoint [as runMain] (internal/modules/run_main.js:74:12)
    at internal/main/run_main_module.js:18:47
error Command failed with exit code 1.

...

To resolve this issue run the following command from a bash prompt (included with git for windows installation):

dos2unix ./packages/\@okta/vuepress-site/conductor.yml

Cannot resolve theme

Due to limitations of the Windows file system you may see the following error after running yarn dev:

yarn run v1.22.4
$ yarn workspace @okta/vuepress-site dev
$ yarn conductor:validate && vuepress dev .
$ node .vuepress/scripts/yml-parse-check.js
conductor.yml parse successful
conductor.yml exports correct values
conductor.yml end-of-file check successful
wait Extracting site metadata...
Error: Cannot resolve theme: @okta/vuepress-theme-prose.
    at resolveTheme (C:\src\repos\okta-developer-docs\node_modules\@vuepress\core\lib\node\loadTheme.js:111:13)
    at loadTheme (C:\src\repos\okta-developer-docs\node_modules\@vuepress\core\lib\node\loadTheme.js:36:17)
    at App.process (C:\src\repos\okta-developer-docs\node_modules\@vuepress\core\lib\node\App.js:100:21)
    at processTicksAndRejections (internal/process/task_queues.js:97:5)
    at async dev (C:\src\repos\okta-developer-docs\node_modules\@vuepress\core\lib\index.js:14:3)
error Command failed with exit code 1.

...

To resolve this issue run the following commands from a bash prompt (included with git for windows installation):

cd ./packages/\@okta/vuepress-theme-prose/
yarn link
cd ../../../
yarn link "@okta/vuepress-theme-prose"

Problem: Sign-In Widget variable (-=OKTA_REPLACE_WITH_WIDGET_VERRSION=-) not pulling in correct version

Major version updates to the SIW need to be updated in the developer.okta.com site's config.js file (packages/@okta/vuepress-site/.vuepress/config.js). Update the signInWidgetMajorVersion constant. See this sample PR: https://github.com/okta/okta-developer-docs/pull/2996/files