{
  "id": "ros2/ros2-launch-substitution-error-command-not-found",
  "signature": "ros2 launch: Substitution error: command 'my_script.sh' not found in PATH or launch directory",
  "signature_zh": "ros2 launch: 替换错误：在PATH或启动目录中找不到命令'my_script.sh'",
  "regex": "Substitution error.*command.*not found|FindExecutable.*failed|ExecuteProcess.*no such file",
  "domain": "ros2",
  "category": "config_error",
  "subcategory": null,
  "root_cause": "The launch file uses a command substitution (e.g., FindExecutable or ExecuteProcess) to locate an executable, but the executable is not in the system PATH or the launch file's package share directory.",
  "root_cause_type": "generic",
  "root_cause_zh": "启动文件使用命令替换（如FindExecutable或ExecuteProcess）来定位可执行文件，但该可执行文件不在系统PATH或启动文件的包共享目录中。",
  "versions": [
    {
      "version": "Humble",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "Iron",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "Rolling",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    }
  ],
  "os_specific": {},
  "dead_ends": [
    {
      "action": "",
      "why_fails": "Even if the script is in the launch directory, the substitution uses the package's share directory, not the source directory. You must install the script via CMake or set the PATH.",
      "fail_rate": 0.9,
      "condition": "",
      "sources": []
    },
    {
      "action": "",
      "why_fails": "Absolute paths work only on the specific machine they were written for. They break when the workspace is moved or shared with other developers.",
      "fail_rate": 0.8,
      "condition": "",
      "sources": []
    }
  ],
  "workarounds": [
    {
      "action": "Ensure the executable is in the PATH. For a shell script in your package, add it to the package's CMakeLists.txt: install(PROGRAMS scripts/my_script.sh DESTINATION lib/${PROJECT_NAME}). Then source the workspace and run: ros2 launch my_package my_launch.py",
      "success_rate": 0.9,
      "how": "Ensure the executable is in the PATH. For a shell script in your package, add it to the package's CMakeLists.txt: install(PROGRAMS scripts/my_script.sh DESTINATION lib/${PROJECT_NAME}). Then source the workspace and run: ros2 launch my_package my_launch.py",
      "condition": "",
      "sources": []
    },
    {
      "action": "Use FindExecutable substitution with the correct package and executable name. In launch file: from launch.substitutions import FindExecutable; executable = FindExecutable(name='my_script.sh'). Ensure the script is installed in the package's lib directory.",
      "success_rate": 0.85,
      "how": "Use FindExecutable substitution with the correct package and executable name. In launch file: from launch.substitutions import FindExecutable; executable = FindExecutable(name='my_script.sh'). Ensure the script is installed in the package's lib directory.",
      "condition": "",
      "sources": []
    },
    {
      "action": "If the script is external, add its directory to PATH before launching: export PATH=$PATH:/path/to/script/dir && ros2 launch my_package my_launch.py",
      "success_rate": 0.75,
      "how": "If the script is external, add its directory to PATH before launching: export PATH=$PATH:/path/to/script/dir && ros2 launch my_package my_launch.py",
      "condition": "",
      "sources": []
    }
  ],
  "workarounds_zh": [
    "Ensure the executable is in the PATH. For a shell script in your package, add it to the package's CMakeLists.txt: install(PROGRAMS scripts/my_script.sh DESTINATION lib/${PROJECT_NAME}). Then source the workspace and run: ros2 launch my_package my_launch.py",
    "Use FindExecutable substitution with the correct package and executable name. In launch file: from launch.substitutions import FindExecutable; executable = FindExecutable(name='my_script.sh'). Ensure the script is installed in the package's lib directory.",
    "If the script is external, add its directory to PATH before launching: export PATH=$PATH:/path/to/script/dir && ros2 launch my_package my_launch.py"
  ],
  "transition_graph": {
    "leads_to": [],
    "preceded_by": [],
    "frequently_confused_with": []
  },
  "official_doc_url": "https://docs.ros.org/en/rolling/Tutorials/Intermediate/Launch/Using-Environment-Variables.html",
  "official_doc_section": null,
  "error_code": null,
  "verification_tier": "ai_generated",
  "confidence": 0.87,
  "fix_success_rate": 0.82,
  "resolvable": "true",
  "first_seen": "2024-04-05",
  "last_confirmed": "2024-06-01",
  "last_updated": "2024-06-01",
  "evidence_count": 1,
  "tags": [],
  "locale": "en",
  "aliases": []
}