Diagnose and resolve contract signing, execution, and document generation errors in SpotDraft. Use this skill when support reports issues like: contract signing failures, 'Word server raised an error', 'Document Generation Unsuccessful', 'SoftTimeLimitExceeded', pre-sign PDF or prepare-for-signing failures, signature fields overlapping or retained after editing, contracts stuck in signing state, unable to send for signing, unable to execute contract, document preview failures, PDF upload errors, corrupt contract versions that block mark-for-execution TXT checks until a clean re-upload succeeds, version selection issues when moving contracts between stages, or any error during the sign/execute workflow. Also trigger on 'signing error', 'execution failed', 'signature fields', 'contract preview', 'document generation failure', 'version mismatch', 'corrupt docx send for signature', or 'template editable' issues.
This covers the second most common category of issues — problems that occur during signing, execution, document generation, or template-to-editable flows.
You have direct access to GCP Cloud Logging and BigQuery for spotdraft-qa. Use these to investigate BEFORE asking humans to check dashboards.
⚠️ MCP only has access to spotdraft-qa project. For QA India contracts, use qa_india_public. For other envs, see the environment mapping below.
Full contract state + signature setup (run first for any signing issue):
SELECT
c.id, c.status, c.contract_kind, c.workflow_status,
c.created, c.modified, c.execution_date,
ss.id as sig_setup_id, ss.is_completed, ss.sent_for_signature,
ss.signing_method, ss.is_deleted as sig_deleted,
ss.mark_executed_after_signatures, ss.signing_order_confirmed
FROM `spotdraft-qa.qa_india_public.contracts_v3_contractv3` c
LEFT JOIN `spotdraft-qa.qa_india_public.contracts_v3_contractsignaturesetup` ss
ON ss.contract_id = c.id AND ss.is_deleted = FALSE
WHERE c.id = {contract_id}
Version history (essential for version mismatch diagnosis):
SELECT
cv.id, cv.version_number, cv.sub_version_number, cv.action,
cv.is_current, cv.is_deleted, cv.deleted_at,
cv.root_version_id, cv.version_description,
cv.docx_version IS NOT NULL as has_docx,
cv.pdf_version IS NOT NULL as has_pdf,
cv.created
FROM `spotdraft-qa.qa_india_public.contracts_v3_contractversion` cv
WHERE cv.contract_id = {contract_id}
ORDER BY cv.version_number DESC, cv.sub_version_number DESC
LIMIT 20
What to look for in version history:
is_current = TRUE → version consistency bugEXECUTION_PDF / UPLOADED_TPP_PDF pattern with many retries → ConvertAPI/document merging repeatedly failingaction values for the stage (WORKING_EDITABLE appearing after move to SIGN stage → version mismatch)is_deleted = TRUE on the expected current version → wrong version selectedApproval state for a contract:
SELECT
a.id, a.name, a.current_state, a.order, a.enforcement_point_type,
a.breakpoint_type, a.approval_type, a.is_deleted
FROM `spotdraft-qa.qa_india_public.approvals_v5_approvalv5` a
WHERE a.linked_to_entity_id = {contract_id}
AND a.linked_to_entity_type = 'CONTRACT'
AND a.is_deleted = FALSE
ORDER BY a.order
| Environment | BQ Project | Dataset | MCP Access |
|---|---|---|---|
| QA India | spotdraft-qa | qa_india_public | ✅ Yes |
| QA EU | spotdraft-qa | qa_eu_public | ✅ Yes |
| QA USA | spotdraft-qa | qa_usa_public | ✅ Yes |
| Dev India | spotdraft-qa | dev_india_public | ✅ Yes |
| Prod IN/EU/US | spotdraft-prod | prod_{region}_db | ❌ Use admin panel |
| Prod MEA | spotdraft-prod | prod_mea_db | ❌ Use admin panel |
Prod tables have a
public_prefix, e.g.prod_india_db.public_contracts_v3_contractversion. QA/Dev have no prefix.
Use list_log_entries with resourceNames: ["projects/spotdraft-qa"] and orderBy: "timestamp desc":
Search Django app logs for signing/execution errors by contract ID:
resource.type="k8s_container" labels."k8s-pod/app"="spotdraft-qa-django-app" textPayload:"{contract_id}" severity >= ERROR
Search for Word server errors:
resource.type="k8s_container" labels."k8s-pod/app"="spotdraft-qa-django-app" textPayload:("Word server raised an error" OR "ConvertAPI" OR "document generation" OR "document conversion")
Search for signing-specific errors:
resource.type="k8s_container" labels."k8s-pod/app"="spotdraft-qa-django-app" textPayload:("signature" OR "signing" OR "execution" OR "Cannot edit a signature setup")
Search deferred tasks worker for async task failures:
resource.type="k8s_container" labels."k8s-pod/app"="spotdraft-qa-django-app-deffered-tasks" textPayload:("{contract_id}" OR "signing" OR "execution") severity >= ERROR
Prod — pre-sign PDF / SoftTimeLimitExceeded (use when incident is on prod): Prod uses jsonPayload, not textPayload. Use resourceNames: ["projects/spotdraft-prod"]. Cluster label for US prod: resource.labels.cluster_name="prod-usa". Deferred tasks workload: sd-apps-django-app-deffered-tasks.
logName="projects/spotdraft-prod/logs/stderr"
resource.labels.cluster_name="prod-usa"
labels."k8s-pod/app"="sd-apps-django-app-deffered-tasks"
jsonPayload.message=~"SoftTimeLimitExceeded|save_pre_sign_pdf|cf_exporter|generate_docx_for_payload"
Always add a time window (e.g. timestamp >= "YYYY-MM-DDTHH:MM:00Z") to limit volume.
Check nginx for upstream timeouts on contract endpoints:
resource.type="k8s_container" resource.labels.namespace_name="kube-system" textPayload:"upstream timed out" textPayload:"/api/v3/contracts/{contract_id}"
Use projectId: "spotdraft-qa" for all queries.
Check DLQ for failed signing/execution tasks:
SELECT task_name, workspace_id, created, signature
FROM `spotdraft-qa.dlq_qa_india.dlq`
WHERE created >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 7 DAY)
AND (task_name LIKE '%sign%' OR task_name LIKE '%execut%' OR task_name LIKE '%convert%' OR task_name LIKE '%document%')
ORDER BY created DESC
LIMIT 20
Check DLQ for a specific workspace's failed tasks:
SELECT task_name, COUNT(*) as failures, MAX(created) as last_failure
FROM `spotdraft-qa.dlq_qa_india.dlq`
WHERE created >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 7 DAY)
AND workspace_id = {wsid}
GROUP BY task_name
ORDER BY failures DESC
LIMIT 20
Check request/response logs for 500 errors on contract endpoints:
SELECT request_path, response_status, time_taken, workspace_id, inserted_at, response_content
FROM `spotdraft-qa.request_response_logs_qa_india.logs`
WHERE inserted_at >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 7 DAY)
AND response_status >= 500
AND request_path LIKE '%contract%'
ORDER BY inserted_at DESC
LIMIT 20
Check request/response logs for a specific contract ID:
SELECT request_path, request_method, response_status, time_taken, response_content, inserted_at
FROM `spotdraft-qa.request_response_logs_qa_india.logs`
WHERE inserted_at >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 7 DAY)
AND request_path LIKE '%{contract_id}%'
ORDER BY inserted_at DESC
LIMIT 20
spotdraft-qa.dlq_qa_india.dlq, spotdraft-qa.request_response_logs_qa_india.logsspotdraft-qa.dlq_qa_europe.dlq, spotdraft-qa.request_response_logs_qa_europe.logsspotdraft-qa.dlq_qa_usa.dlq, spotdraft-qa.request_response_logs_qa_usa.logsAsk the support person for:
https://app.spotdraft.com/contracts/v2/{id})Most signing/execution operations are async. Check the admin panel: