Troubleshooting
- Getting more detailed error information
- What is the required Node version?
- Issues seen with npm
- Browser crashes and startup errors
- Problems when running the executable
- Window is solid black or solid white; looks like a blank page
Starting Brave via the command line will help collect more info. Additionally, we have some environment variables which can be set prior to launch that will output more info.
- Start > Run > cmd.exe
cd %userprofile%\AppData\Local\brave- set any environment variables. For example, to collect more info useful for Brave Payments / ledger:
set LEDGER_PUBLISHER_VERBOSE=true
- run
.\app-0.12.2\Brave.exe(where app-0.12.2 is the current version of Brave)
- Set environment variables ahead of time OR prepend them to the command ran in step 2
- Launch Brave
- `LEDGER_PUBLISHER_VERBOSE=true /Applications/Brave/Contents/MacOS/Brave
Brave does not work with node.js < 5.0. Please use Node 7 or newer
See Upgrading node.js on Debian and Ubuntu
While running npm install you will likely see lines like the following which may be safely ignored
npm WARN deprecated [email protected]: Deprecated.
npm WARN install Couldn't install optional dependency: Unsupported
If this fails on Linux with an error related to abp-filter-parser-cpp, try updating to Node 5.5 and node-gyp 3.2.1 (see discussion at https://github.com/brave/browser-laptop/issues/214)
If installing on a new machine with little or no node.js previously installed this can take a long time, especially if you are outside the USA and/or have limited bandwidth. In such cases you may also get timeouts which result in failures due to ECONNRESET messages or similar. If this happens. you should simply rerun the npm install command until these stop
If you're inside a tmux session, you might encounter an issue when the npm install gets to showing the toast notification when the webpack build is complete. If you exit out of tmux and instead use iTerm2 to split your panes, it should work as expected. If you'd like to keep using tmux, you should be able to control+c when the npm install gets to that part (since the build is finished).
If you're using Cygwin, npm currently has a known issue which is considered wont-fix. While Cygwin is not supported by npm, Inc, you can resolve this issue yourself by patching npm yourself. An alternative is to use the GitHub for Windows shell.
Visual Studio 2015 may require additional configuration, which you can read about here.
Since brave has a client and server section, it is necessary to ensure that the two communicate on an unused port. Brave uses port 8080 to communicate between its client and server sides by default. If you are using port 8080 for something else (e.g. a web proxy) then you can set the environment variable BRAVE_PORT to make it use a different one.
e.g.
BRAVE_PORT=9001 npm run watch
BRAVE_PORT=9001 npm start
The server section started by run watch does NOT stop when the client quits. You should generally manually terminate the server side before updating to the latest build. There is currently no clean way to do this. One method that works is
kill `ps ax | grep browser-laptop | awk '{print }' | head -n 1`
or on macOS:
pkill -f browser-laptop
Needs more investigation
Needs more investigation
Needs more investigation
Needs more investigation Example cause:
An uncaught exception occurred in the main process Uncaught Exception:
TypeError: Parameter "url" must be a string, not object
at Url.parse (url.js:87:11)
at Object.urlParse [as parse] (url.js:81:5)
at Array.Filtering.registerBeforeRequestFilteringCB (/Users/bjohnson/Documents/brave/browser-electron/app/adBlock.js:38:31)
at Function.session.webRequest.onBeforeRequest (/Users/bjohnson/Documents/brave/browser-electron/app/filtering.js:106:49)
Cause may be related to javascript errors occurring within a native callback
The exception occurred inside loadAppStatePromise.then - https://github.com/brave/browser-laptop/issues/4477
Browser starts and there is an icon in the dock (macOS), hangs for a while and then crashes with a dialog to report the error (macOS)
Needs more investigation
Browser starts and opens the window, but never loads the main frame and there is a stack trace in the browser dev console
This occurs when there is a javascript error in the main window and it is usually a problem with the react code. You can view the stack trace in the browser dev tools (cmd/ctrl-F8)
Also if you are trying to launch Brave with another Electron app such as the Hyper terminal you may experience this problem and see an error like:
Uncaught ReferenceError: AIzaSyAQfxPJiounkhOjODEO5ZieffeBv6yft2Q is not defined browser.js:148
in the browser dev tools. This is caused by both Electron apps setting the same env variable GOOGLE_API_KEY.
You can fix this by running
unset GOOGLE_API_KEY
in your terminal. You can also add that line to your ~/.bashrc so it unsets automatically on terminal load.
This is a crash in the renderer process for the tab and is either a problem with a content script (usually produces a javascript error in the console and doesn't crash) or more likely an issue in electron.
This has been reported with several issues:
- #1471 - Blank Page on Ubuntu
- #3180 - Brave does not run properly in Linux Mint 18 XFCE in Virtual Box
- #6022 - Blank page when 2 tabs or more
The root cause appears to be that Chromium is having a problem with hardware acceleration. Disabling hardware acceleration in our preferences screen (if you're able to get that far) doesn't always work. We do have a documented issue to make this easier to try... but in the meantime, here are some steps you can take.
- Right click the Brave shortcut and pick properties
- In the
Targetarea, paste in--disable-gpuat the end - Click Apply and close the window
- Launch the shortcut you just changed
Screenshot:
