Fix Jinja2 template errors from invalid parameter/block names with special characters (SKY-7356) (#4644)

skyvern/forge/sdk/routes/agent_protocol.py

@@ -118,7 +118,13 @@ from skyvern.schemas.runs import (
     WorkflowRunResponse,
 )
 from skyvern.schemas.webhooks import RetryRunWebhookRequest
-from skyvern.schemas.workflows import BlockType, WorkflowCreateYAMLRequest, WorkflowRequest, WorkflowStatus
+from skyvern.schemas.workflows import (
+    BlockType,
+    WorkflowCreateYAMLRequest,
+    WorkflowRequest,
+    WorkflowStatus,
+    sanitize_workflow_yaml_with_references,
+)
 from skyvern.services import block_service, run_service, task_v1_service, task_v2_service, workflow_service
 from skyvern.services.pdf_import_service import pdf_import_service
 from skyvern.webeye.actions.actions import Action
@@ -536,6 +542,9 @@ async def create_workflow_legacy(
     except yaml.YAMLError:
         raise HTTPException(status_code=422, detail="Invalid YAML")
 
+    # Auto-sanitize block labels and update references for imports
+    workflow_yaml = sanitize_workflow_yaml_with_references(workflow_yaml)
+
     try:
         workflow_create_request = WorkflowCreateYAMLRequest.model_validate(workflow_yaml)
         # Override folder_id if provided as query parameter
@@ -588,6 +597,8 @@ async def create_workflow(
     try:
         if data.yaml_definition:
             workflow_json_from_yaml = yaml.safe_load(data.yaml_definition)
+            # Auto-sanitize block labels and update references for imports
+            workflow_json_from_yaml = sanitize_workflow_yaml_with_references(workflow_json_from_yaml)
             workflow_definition = WorkflowCreateYAMLRequest.model_validate(workflow_json_from_yaml)
         elif data.json_definition:
             workflow_definition = data.json_definition

skyvern/forge/sdk/workflow/exceptions.py

@@ -166,7 +166,10 @@ class InvalidWaitBlockTime(SkyvernException):
 class FailedToFormatJinjaStyleParameter(SkyvernException):
     def __init__(self, template: str, msg: str) -> None:
         super().__init__(
-            f"Failed to format Jinja style parameter {template}. Please make sure the variable reference is correct. reason: {msg}"
+            f"Failed to format Jinja style parameter '{template}'. "
+            f"Reason: {msg}. "
+            "If your block labels or parameter keys contain characters like '/', '-', or '.', "
+            "please rename them to use only letters, numbers, and underscores (e.g., 'State_Province' instead of 'State/Province')."
         )
 
 
@@ -175,7 +178,9 @@ class MissingJinjaVariables(SkyvernException):
         self.variables = variables
 
         super().__init__(
-            f"There are missing variables for '{template}'. Please make sure the variables are supplied. Missing variables: {variables}"
+            f"Missing variables for '{template}'. Missing: {variables}. "
+            "If your block labels or parameter keys contain characters like '/', '-', or '.', "
+            "please rename them to use only letters, numbers, and underscores (e.g., 'State_Province' instead of 'State/Province')."
         )