[v3] Shell metacharacters not allowed when trying to open a link

[Etesam913]

Description

I get this in my terminal:

2:04PM ERR Invalid URL: shell metacharacters not allowed error="shell metacharacters not allowed"

when trying to open a this link: "https://en.wikipedia.org/wiki/Tenth_Avenue_(Manhattan)".

To Reproduce

Here is my code

import { Browser } from '@wailsio/runtime';
import { toast } from 'sonner';
import { DEFAULT_SONNER_OPTIONS } from '../../../utils/general';

/** Opens the link in the browser when clicked */
export function handleATagClick(target: HTMLElement) {
  const parentElement = target.parentElement as HTMLLinkElement;
  if (parentElement.href.startsWith('wails://')) {
    return;
  }
  console.log(parentElement.href.toString());
  Browser.OpenURL(parentElement.href).catch(() => {
    toast.error(
      `Failed to open link: ${parentElement.href}`,
      DEFAULT_SONNER_OPTIONS
    );
  });

I get this error message in my application:

and I get this error message in my terminal:

2:04PM ERR Invalid URL: shell metacharacters not allowed error="shell metacharacters not allowed"

Expected behaviour

The link opens in my browser

Screenshots

No response

Attempted Fixes

No response

System Details

etesam@etesams-MacBook-Air ~/C/bytebook ((b6421c8f))> wails3 dcotor
wails v3 - The Wails3 CLI

Available commands:

   docs           Open the docs 
   init           Initialise a new project 
   build          Build the project 
   dev            Run in Dev mode 
   package        Package application 
   doctor         System status report 
   releasenotes   Show release notes 
   task           Run and list tasks 
   generate       Generation tools 
   update         Update tools 
   service        Service tools 
   tool           Various tools 
   version        Print the version 
   sponsor        Sponsor the project 

Flags:

  -help
        Get help on the 'wails' command.


Need documentation? Run: wails3 docs
 ♥   If Wails is useful to you or your company, please consider sponsoring the project: wails3 sponsor
etesam@etesams-MacBook-Air ~/C/bytebook ((b6421c8f))> wails3 doctor
 Wails (v3.0.0-dev)  Wails Doctor 
                                                                                                                                                                                  
# System 

┌──────────────────────────────────────────────────┐
| Name          | MacOS                            |
| Version       | 26.1                             |
| ID            | 25B5072a                         |
| Branding      | MacOS 26.1                       |
| Platform      | darwin                           |
| Architecture  | arm64                            |
| Apple Silicon | true                             |
| CPU           | Apple M2                         |
| CPU 1         | Apple M2                         |
| CPU 2         | Apple M2                         |
| GPU           | 10 cores, Metal Support: Metal 4 |
| Memory        | 24 GB                            |
└──────────────────────────────────────────────────┘

# Build Environment 

┌─────────────────────────────────────────────────────────┐
| Wails CLI    | v3.0.0-dev                               |
| Go Version   | go1.24.3                                 |
| Revision     | 84fcd705cc3d8cf0dfec46aee82570491640c154 |
| Modified     | false                                    |
| -buildmode   | exe                                      |
| -compiler    | gc                                       |
| CGO_CFLAGS   |                                          |
| CGO_CPPFLAGS |                                          |
| CGO_CXXFLAGS |                                          |
| CGO_ENABLED  | 1                                        |
| CGO_LDFLAGS  |                                          |
| GOARCH       | arm64                                    |
| GOARM64      | v8.0                                     |
| GOOS         | darwin                                   |
| vcs          | git                                      |
| vcs.modified | false                                    |
| vcs.revision | 84fcd705cc3d8cf0dfec46aee82570491640c154 |
| vcs.time     | 2025-10-03T03:39:41Z                     |
└─────────────────────────────────────────────────────────┘

# Dependencies 

┌────────────────────────────────────────────────────────────────────────┐
| Xcode cli tools | 2416                                                 |
| npm             | 11.4.2                                               |
| *NSIS           | Not Installed. Install with `brew install makensis`. |
|                                                                        |
└─────────────────────── * - Optional Dependency ────────────────────────┘

# Checking for issues 

 SUCCESS  No issues found

# Diagnosis 

 SUCCESS  Your system is ready for Wails development!

Need documentation? Run: wails3 docs
 ♥   If Wails is useful to you or your company, please consider sponsoring the project: wails3 sponsor

Additional context

No response

[symball]

This is expected. Parenthesis are considered a special control character in shell syntax so gets flagged as unsafe, only valid in the query part of the URL.

Encode the URL like "https://en.wikipedia.org/wiki/Tenth_Avenue_%28Manhattan%29" and it should be OK

Even better would be to have a dedicated binding and call that instead of the BrowserOpenURL method. The following uses go net/url to sanitize things for you

import (
    "net/url"
    "github.com/wailsapp/wails/v2/pkg/runtime"
)

func OpenSafeURL(ctx context.Context, raw string) error {
    parsed, err := url.Parse(raw)
    if err != nil {
        return err
    }

    encoded := parsed.String()
    return runtime.BrowserOpenURL(ctx, encoded)
}

[leaanthony]

Would it make sense for BrowserOpenURL to do the escaping for you?

[symball]

@leaanthony i took a quick look at this and realised there was an custom url validator there. I switched it out for the built in function which both validates and sanitizes for us

[leaanthony]

Triage notes:

• Classification: Bug (v3) — Shell metacharacters (like &, |, ;) in URLs cause errors when Wails tries to open them via the system shell.
• Labels applied: v3
• Platform: Not specified in the report. Could you share your OS and Wails version? This affects the application.OpenURL / shell execution path, so the fix approach differs by platform.

[leaanthony]

🤖 Triage note: This issue appears to be a cross-platform runtime bug (URL opening via Browser.OpenURL). The reproduction steps are clear. No additional labels proposed — current labels (Bug, v3) seem appropriate.