Building Desktop Apps with Wails #8 Debugging — Dev Tools, Logs, Common Errors

Framework Wails Go Desktop
5 min read

The final post of the series. Where the previous seven were “what to build and how,” this one is “how to find it when it breaks.” It covers the areas where beginners most often get stuck in Wails — blank screens, binding errors, environment issues — and how to catch them with dev tools and logs. Knowing how to debug lets you go straight to the cause instead of repeating searches when stuck.

This series is six main posts plus two deep-dives, eight in all.

Dev tools: looking into the frontend #

A Wails app’s screen is drawn by the OS WebView, so you can use the same dev tools as a browser. In development mode launched with wails dev, the dev tools are on by default. Right-click the window to open Inspect, or open it with a shortcut. From there you see the DOM, network, and the frontend console just like a browser.

Note that in a distribution app built with wails build, the dev tools are off by default. When you need to reproduce a problem in a shipped app, use the -debug build described below.

Logs: both frontend and Go #

A Wails app joins two worlds, so logs come from two places.

  • Frontend logs: console.log prints to the dev tools console. Same as a browser.
  • Go logs: runtime.LogInfo, LogError, and so on, covered in #5. When you run with wails dev, these Go logs print to the terminal. Look at the terminal you launched the app from, not the frontend console.

When separating whether a problem is on the frontend or in Go, reading the two logs separately is the first step. A failed binding call shows a rejected Promise in the frontend console; something going wrong inside Go shows a log in the terminal.

Common error 1: the window opens but the screen is blank #

The most frequent symptom. The window opens but is white and empty inside. The cause is usually that the frontend build output is not where Wails expects it.

  • The frontend was not built (frontend:build failed), or Vite’s output path diverges from where Wails expects (frontend/dist). This comes up often when attaching a framework in #7.
  • Open the dev tools console and there is usually a file-not-found 404 or a JavaScript error, revealing which it is right away.

When you hit a blank screen, do not guess — open the dev tools console first. Even with an empty screen, the console tells you the cause.

Common error 2: binding not found #

You call a Go method from the frontend but get “no such function” or a broken import. The checklist:

  • Did the method follow the exposure rules: to be bound, the App struct’s method must start with a capital letter (exported) and be registered in the bindings list at app creation (see #3).
  • Were the bindings regenerated: the bindings in the wailsjs folder are rebuilt by wails dev or wails build from your Go code. If you added a new method and it does not appear, restart the dev server to regenerate the bindings.

That is, checking “capitalized, registered, regenerated” in order catches most cases.

Common error 3: the context is nil #

You call a Go runtime function (runtime.EventsEmit, runtime.WindowShow, and the like) and the app crashes or nothing happens. These functions take a context.Context, and that value is valid only after OnStartup is called. Calling a runtime function before the app fully starts fails because the context is empty.

app.go — save the context in OnStartup 
func (a *App) startup(ctx context.Context) {
	a.ctx = ctx // from this point you can safely use runtime functions
}

Call runtime functions after startup, with the saved a.ctx. It is an initialization-order problem, so logging when it was called reveals it quickly.

Diagnosing a shipped app: the -debug build #

Sometimes it is fine in wails dev but the problem appears only in the built app. Then build with dev tools and logs on.

build with dev tools and logs enabled 
wails build -debug

An app built with -debug runs the same way as the distribution build but lets you open the dev tools and keeps logs. Use it to reproduce a “bug that only appears when built” that development mode does not catch. Once you find the cause, build again without -debug to ship.

Environment problems: wails doctor #

If the build itself fails or behaves strangely, suspect the environment before the code. wails doctor, introduced in #1, checks the environment — Go version, WebView runtime, required dependencies — and tells you what is missing. Much of “my code is unchanged but it suddenly broke” is an OS update or a dependency change, so when stuck, run wails doctor once.

Summary #

  • Dev tools are on by default in wails dev. Open them by right-clicking the window to see the DOM, network, and console like a browser. In a built app they are off by default.
  • Logs are in two places. The frontend’s console.log goes to the dev tools; Go’s runtime.LogX goes to the terminal you ran wails dev from.
  • A blank screen is usually because the frontend build output is not where expected. Do not guess — open the console first.
  • If a binding is not found, check capitalized export, binding registration, and regeneration. If the context is nil, check that you call after OnStartup.
  • Reproduce built-app-only problems with wails build -debug, and if the build itself fails, check the environment first with wails doctor.
  • That concludes the Building Desktop Apps with Wails series. To go deeper, the Wails in Practice course builds a single app all the way to shipping and polish.
X