Skip to content

1.6-recover.md

Latest commit

 

History

History
110 lines (76 loc) · 3.5 KB

1.6-recover.md

File metadata and controls

110 lines (76 loc) · 3.5 KB
title Recovery Procedures
description Diagnose failures and resume the onboarding workflow with ranked recovery options

Recovery Procedures

When any step in the onboarding workflow fails, use this guide to diagnose the issue and get back on track.

Step 1: Identify the Failure

Note which step failed and the specific error:

Failed Step Common Errors
Detect Unable to identify language or framework
Plan Multiple SDKs could apply; ambiguous stack
Apply Install command failed; import errors; code doesn't compile
Run Application won't start; SDK initialization error
Validate SDK not showing as active; API errors
First Flag Flag creation failed; evaluation returns unexpected value

Step 2: Choose a Recovery Action

Recovery options are listed in priority order. Start with option 1 and work down.

Option 1: Retry Current Step

Re-attempt the failed step after reviewing the error output. Many issues are transient (network timeouts, temporary API errors) or are fixed by correcting a small mistake.

Option 2: Verify Credentials

Confirm the LaunchDarkly access token and SDK key are valid:

# Test API access
curl -s -X GET \
  "https://app.launchdarkly.com/api/v2/projects" \
  -H "Authorization: YOUR_ACCESS_TOKEN"

Or via ldcli:

ldcli environments list --project PROJECT_KEY --access-token YOUR_ACCESS_TOKEN

If this fails with 401, the token is invalid or expired. Ask the user to provide a valid token.

Option 3: Check Network Connectivity

The SDK needs outbound HTTPS access to:

  • app.launchdarkly.com (API)
  • stream.launchdarkly.com (streaming)
  • events.launchdarkly.com (events)

Test connectivity:

curl -s -o /dev/null -w "%{http_code}" https://app.launchdarkly.com/api/v2

If the network is blocked, advise the user to check firewall rules and proxy settings.

Option 4: Manual SDK Install

If automatic dependency installation fails, provide the user with copy/paste instructions:

  1. Show the exact package name and version from the SDK Recipes
  2. Provide the manual install command
  3. Ask the user to run it themselves and confirm completion

Option 5: Try Alternative SDK

If the detected SDK was wrong:

  1. Ask the user what language/framework they're targeting
  2. Let them manually select from the SDK Recipes
  3. Restart from the Plan step with the correct SDK

Option 6: Skip to Next Step

If the failure is non-critical, skip ahead:

  • Can't auto-run the app? Ask the user to start it manually, then continue to Validate
  • Can't validate via API? Ask the user to check the LaunchDarkly dashboard
  • Can't create a flag programmatically? Walk the user through creating it in the dashboard

Option 7: Abort Onboarding

If the issue can't be resolved:

  1. Summarize what was accomplished (which steps succeeded)
  2. Provide links for manual setup:
  3. Suggest the user reach out to LaunchDarkly support

Automatic Escalation

If the same step fails 3 times, automatically suggest:

  • Skipping the step (if non-critical)
  • Aborting and providing manual instructions
  • Asking the user for help with the specific error

Status

[STATUS] Diagnosing failure in step: [step name]
[STATUS] Attempting recovery: [recovery option]
[STATUS] Resuming workflow from step: [step name]