Skip to content

[cli] Hint at troubleshooting docs on timeout#4821

Open
ShadiBahaa wants to merge 1 commit intocanonical:mainfrom
ShadiBahaa:cli-launch-timeout-troubleshoot-hint
Open

[cli] Hint at troubleshooting docs on timeout#4821
ShadiBahaa wants to merge 1 commit intocanonical:mainfrom
ShadiBahaa:cli-launch-timeout-troubleshoot-hint

Conversation

@ShadiBahaa
Copy link
Copy Markdown
Contributor

@ShadiBahaa ShadiBahaa commented Apr 14, 2026

Summary

When multipass launch times out waiting for an instance to become ready (e.g. due to a firewall blocking DHCP, or network misconfiguration), the error message provides no guidance on what to try next.

This adds a link to the troubleshooting documentation when the launch failure indicates a timeout, giving users a starting point to diagnose the issue.

Before:

launch failed: The following errors occurred:
test-vm: timed out waiting for response

After:

launch failed: The following errors occurred:
test-vm: timed out waiting for response
For troubleshooting, see https://documentation.ubuntu.com/multipass/stable/how-to-guides/troubleshoot/

Based on reviewer feedback from #4500:

  • Does not mention any specific cause (multiple causes are possible)
  • Points to the general troubleshooting page rather than a specific sub-page
  • Uses a single string construction

Test plan

  • Verify that launch timeouts now include the troubleshooting link in the error output
  • Verify that non-timeout launch failures (invalid disk size, invalid hostname, etc.) are unaffected
  • Verify that the INVALID_NETWORK error still shows its own troubleshooting link

Closes #533

When a launch times out waiting for the instance to become
ready, the error message gives no guidance on what to try.

Append a link to the troubleshooting documentation when the
launch failure message indicates a timeout, so users have a
starting point to diagnose the issue.

Closes: canonical#533
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Suggest opening up firewall when launching times out

1 participant