Skip to content

Latest commit

 

History

History
316 lines (230 loc) · 18.9 KB

Troubleshooting.md

File metadata and controls

316 lines (230 loc) · 18.9 KB
Raw

Local troubleshooting

This document was created to provide solutions to common issues that occur when running the frontend locally. The issues are categorised by the method used to bring up the application.

When updating this document please use the following template:

### Issue title
[brief description of issue]

Screenshot:

![image-title](./Troubleshooting/[image-name].png 'Textual representation of the error for it to be picked up in a search')

**Solution** If there is a single permanent fix for this issue enter it here.

**Short-term fix** If there is a temporary workaround or some of 'sticky-tape' solution enter it here.

**Long-term fix** If there is a permanent fix for the issue (or if one is being worked on) enter it here.

Docker issues

This section should include issues that occur when running the frontend in Docker.

Native issues

This section should be used for native issues that occur regardless of what API you are using.

Missing environment variable

This error appears if one or more of the required environment variables is missing or has no value set. The error message will tell you which variables need to be changed.

![missing-env-var](./Troubleshooting/native-generic-missing-envvar.png ' COMPANY_MATCHING_SERVICE_BASE_URL": "http://mock-third-party-services:8888\* "COMPANY_MATCHING_HAWK_ID": "dummyId", "COMPANY_MATCHING_HAWK_KEY": "dummyKey", "OAUTH2_BYPASS_SSO": "true", "OAUTH2_LOGOUT_URL": "http://anyurl/o/logout", "OAUTH2_AUTH_URL": "http://anyurl/o/authorize", "OAUTH2_DEV_TOKEN" [1]: -- missing }

[1] "OAUTH2_DEV_TOKEN" is required ValidationError: { "TERM_PROGRAM": "vscode", "NODE": "/Users/christophersunkel/.nvm/versions/node/v16.15.1/bin/node", "INIT_CWD": "/Users/christophersunkel/Documents/datahub/data-hub-frontend", "NVM_CD_FLAGS": "-q", "TERM": "xterm-256color", "SHELL":"/bin/zsh", "npm_config_metrics_registry": "https://registry.npmjs.org/", "TMPDIR": "/var/folders/wh/6db7nz9j6xg7wbc5r25lzc9r0000gn/T/",')

Solution Assign a value to the missing variable.

Unsupported engine error

This error occurs when your local Node version is incorrect.

wrong-node-version

Short-term fix Run the command nvm use [required version] (you may need to run nvm install [version] first).

Long-term fix Set your default NVM alias to the required version.

Running natively against a local API instance

Error connecting to Redis

This error usually appears if there is a mismatch between your local API and frontend env files, or if one of your env files has incorrect/outdated environment variables set.

error-connecting-to-redis

Solution Ensure that any shared environment variables are correct and are set to the same value in both projects.

Error fetching metadataRepository

This error occurs when the frontend can't connect to your local API instance.

metadata-error

Solution Ensure that your API_ROOT variable has been set correctly. The local API will use http://localhost:8000.

This error can occur when the connection to a Native installation (withouth Docker) of the Data Hub API is refused.

native-api-econnrefused

Solution When connecting to native/local Data Hub API ensure that

  • in the API's .env file the LOCAL_DEV=True is set to True and
  • in the Front End's .env file the API_ROOT=http://127.0.0.1:8000 uses 127.0.0.1 rather than localhost.

Running natively against a live environment (dev/staging)

Error connecting to Redis

When running against a live environment, this error usually occurs if you run npm run develop without a local Redis instance running, or if you have incorrect environment variables.

redis-error

Solution Close your frontend instance, then start a new native redis instance (follow the redis setup instructions if you have not done this before).

Once this is running, you should update the following environment variables:

  • REDIS_HOST should be set to localhost
  • REDIS_URL should be set to redis://localhost:6379
  • DATA_HUB_BACKEND_ACCESS_KEY_ID and DATA_HUB_BACKEND_SECRET_ACCESS_KEY should be set to the values from Vault (if working with the investment homepage, you will need to do the same for all variables with the prefix HELP_CENTRE or the page will not load).

Once this is done, the app should start after running npm run develop.

Invalid authentication details

This error occurs when your OAUTH2_DEV_TOKEN is out of date or hasn't been set correctly.

redis-error

Solution Bring down your frontend and remove the current value for OAUTH2_DEV_TOKEN. Generate a new access token by navigating to the relevant /add-access-token/ page (for convenience you can set this to last for up to 168 hours), then set the value of OAUTH2_DEV_TOKEN to the newly-generated token. The frontend should now work after running npm run develop.

'System down' page appears

This error occurs when your local redis server is brought down whilst the app is still running.

system-down

Solution Bring down your local frontend, restart your redis instance and run npm run develop. The frontend should then work as expected.

Unexpected token < in JSON at position 0

This error is caused when you try to connect to a live environment without turning the VPN on.

vpn-error

Solution Bring down your local frontend, enable the VPN and then run npm run develop again. The frontend should now work correctly.

Test Issues

This section is for issues when running tests locally in accordance with the running tests documentation.

Visual & Visual Component Tests

Visual and visual-component tests should always be run within docker (using the make commands) to ensure the screenshot resolutions are consistent, otherwise you may find the tests fail with an error message similar to Error: Image difference greater than threshold: 0.

However, when running the make commands on Macs with Apple chips, you may come across errors with Cypress or the test runners failing to start:

> test:visual-component
> CYPRESS_coverage=false cypress run --config-file cypress.visual.config.js --config '{"specPattern":["test/visual-component/cypress/specs/**/*.js"]}' --browser chrome

qemu: uncaught target signal 5 (Trace/breakpoint trap) - core dumped
qemu: uncaught target signal 5 (Trace/breakpoint trap) - core dumped
qemu: uncaught target signal 11 (Segmentation fault) - core dumped
The Test Runner unexpectedly exited via a exit event with signal SIGSEGV

Please search Cypress documentation for possible solutions:

https://on.cypress.io

Check if there is a GitHub issue describing this crash:

https://github.com/cypress-io/cypress/issues

Consider opening a new issue.

----------

Platform: linux-x64 (Debian - 10)
Cypress Version: 12.17.4
make: *** [visual-component-tests] Error 1

Solution: ensure you have checked the following and then re-build/re-run the containers/make commands.

  • Have Rosetta 2 installed on your Mac (see Apple's support page for more information on this)
  • Have the latest version of Docker Desktop installed
  • Have enabled the Use Rosetta for x86/amd64 emulation on Apple Silicon setting under the general tab in Docker Desktop

Visual & Visual Component Tests Hanging

After following the above steps, you may find the visual tests eventually start, but get stuck (or hang) on the first. You might see console output similar to:

> test:visual
> CYPRESS_coverage=false cypress run --config-file cypress.visual.config.js --config '{"specPattern":["test/visual/cypress/specs/**/*.js"]}' --browser chrome

[1356:0126/105317.072419:ERROR:node_bindings.cc(279)] Most NODE_OPTIONs are not supported in packaged apps. See documentation for more details.

DevTools listening on ws://127.0.0.1:35493/devtools/browser/c8f21391-8172-4dfa-bcf9-dd69079a53fe
libva error: vaGetDriverNameByIndex() failed with unknown libva error, driver_name = (null)
[1566:0126/105318.610695:ERROR:gpu_memory_buffer_support_x11.cc(44)] dri3 extension not supported.
Couldn't find tsconfig.json. tsconfig-paths will be skipped

====================================================================================================

  (Run Starting)

  ┌────────────────────────────────────────────────────────────────────────────────────────────────┐
  │ Cypress:        12.17.4                                                                        │
  │ Browser:        Chrome 106 (headless)                                                          │
  │ Node Version:   v18.15.0 (/usr/local/bin/node)                                                 │
  │ Specs:          7 found (community-spec.js, company-spec.js, contact-spec.js, event-spec.js, i │
  │                 nteraction-spec.js, investment-spec.js, omis-spec.js)                          │
  │ Searched:       test/visual/cypress/specs/**/*.js                                              │
  └────────────────────────────────────────────────────────────────────────────────────────────────┘


────────────────────────────────────────────────────────────────────────────────────────────────────

  Running:  community-spec.js                                                               (1 of 7)


  community page
Hangs here...

Preliminary results point to this being an issue only for those on M1 and M2 machines when trying to run the tests locally, within Docker. We think this is due to an incompatibility between the docker images and the ARM architecture, however, we are still investigating this.

Please note that CircleCI should continue to run the tests without problems.