Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

iOS devices: `open <app> <url>` never delivers the URL, `--payload-url` is passed after the bundle ID

Open Beginner friendly
  • Is something wrong?
#2,998 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
88/100
Issue type
Bug
Clarity
Clearly specified
Activity status
Active
Tech stack
ios, typescript
Domain
cli, mobile-dev, testing-qa

Research direction

Start in packages/platform-apple/src/core/physical-device-coredevice.ts at the launch-argument construction, then compare it with the expectations in packages/platform-apple/src/core/tests/apps.test.ts. Run the relevant apps tests and verify that the payload URL is treated as a launch option and delivered on physical iOS devices while launch arguments remain supported.

Written by the indexing model from the issue text.

Description

Summary

On a physical iPhone, open <bundle-id> <url> and Maestro openLink launch the app, but the app never receives the URL. The same call with devicectl works when --payload-url comes before the bundle ID.

Cause

The launch arguments put --payload-url after the bundle ID:

https://github.com/callstack/agent-device/blob/16e07572ab28227563fd76ab062cb375c4b7e1db/packages/platform-apple/src/core/physical-device-coredevice.ts#L24-L27

devicectl treats everything after the bundle ID as program arguments for the app:

USAGE: devicectl device process launch [<options>] --device <...> <bundle-identifier-or-path> [<command-line-arguments> ...]

So the app receives --payload-url <url> in its argv and opens no link. The unit test pins the same order:

https://github.com/callstack/agent-device/blob/16e07572ab28227563fd76ab062cb375c4b7e1db/packages/platform-apple/src/core/__tests__/apps.test.ts#L256-L267

Repro

Same device, same app state (app running on its first screen), custom-scheme link to a screen with a visible marker:

Call Link opens
devicectl device process launch --device <udid> <bundle-id> --payload-url <url> no
devicectl device process launch --device <udid> --payload-url <url> <bundle-id> yes
agent-device open <bundle-id> <url> --platform ios --udid <udid> no

A cold launch with --payload-url before the bundle ID also opens the link.

Possible fix

Push --payload-url <url> before the bundle ID, and keep -- <launch args> after it. Update the two expectations in apps.test.ts.

Environment

  • agent-device 0.21.14. Same code in 0.21.15 and on main at 16e0757
  • iPhone 14 Pro, iOS 26.2, USB, CoreDevice backend
  • Xcode 26.4
Dominant language
TypeScript
Stars
4.7k
Forks
304
Avg merge
11h 31m
Merged PRs (30d)
513

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from callstack/agent-device

All issues in callstack/agent-device

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.