Server Script Errors — Diagnosis and Resolution

Cross-refs:

frappe-syntax-serverscripts

frappe-impl-serverscripts

frappe-errors-clientscripts

CRITICAL: Server Scripts Disabled by Default [v15+]

Starting from Frappe v15, Server Scripts are disabled by default. You MUST enable them:

# In site_config.json
{ "server_script_enabled": 1 }

On Frappe Cloud: Server Scripts are ONLY available on private benches, NOT on shared benches.

Error Diagnosis Flowchart

ERROR IN SERVER SCRIPT
│
├─► ImportError / NameError
│   ├─► "import json" → BLOCKED. Use frappe.parse_json()
│   ├─► "import datetime" → BLOCKED. Use frappe.utils
│   ├─► "import os/sys/subprocess" → BLOCKED. Security restriction
│   └─► "NameError: name 'dict' is not defined" → Some builtins restricted
│
├─► SyntaxError: not allowed
│   ├─► "try/except" → BLOCKED by RestrictedPython [v14-v15]
│   ├─► "raise ValueError" → BLOCKED. Use frappe.throw()
│   └─► "exec/eval" → BLOCKED. Security restriction
│
├─► Script runs but nothing happens
│   ├─► Wrong Script Type selected → Check Document Event vs API vs Scheduler
│   ├─► Wrong DocType selected → Verify exact DocType name
│   ├─► Wrong Event selected → Before Save ≠ After Save
│   └─► Script disabled → Check "Enabled" checkbox
│
├─► 403 Permission Denied
│   ├─► Scheduler script → Runs as Administrator, check role permissions
│   ├─► API script → Check Allow Guest setting
│   └─► doc_event → User lacks DocType permission
│
├─► Data not saved in Scheduler
│   └─► Missing frappe.db.commit() → REQUIRED in scheduler scripts
│
└─► API script returns empty/wrong response
    └─► Not setting frappe.response["message"] → ALWAYS set response

Error Message → Cause → Fix Table

ImportError: import not allowed

import

frappe.utils

frappe.parse_json()

NameError: name 'dict' is not defined

frappe._dict()

{}

SyntaxError: try/except not allowed

if/else

SyntaxError: raise not allowed

raise

frappe.throw()

Script not executing

doc is not defined

doc

doc

PermissionError

ignore_permissions=True

Changes not saved

frappe.db.commit()

frappe.db.commit()

API returns empty response

frappe.response["message"]

frappe.response["message"] = result

Timeout / killed

limit

ValidationError: qty is required

doc.save()

doc.save()

SQL injection via string format

frappe.db.escape()

The #1 Error: ImportError

Every beginner hits this. The Server Script sandbox blocks ALL imports except

json

# ❌ BLOCKED — These ALL fail with ImportError
import json                    # Use frappe.parse_json() / frappe.as_json()
from datetime import datetime  # Use frappe.utils.now(), frappe.utils.today()
import re                      # Not available in sandbox
import os                      # Security: blocked
import requests                # Use frappe.make_get_request(), frappe.make_post_request()

# ✅ CORRECT — Sandbox equivalents
data = frappe.parse_json(doc.json_field)         # Instead of json.loads()
today = frappe.utils.today()                      # Instead of datetime.date.today()
now = frappe.utils.now()                          # Instead of datetime.now()
diff = frappe.utils.date_diff(date1, date2)       # Instead of timedelta
resp = frappe.make_get_request("https://api.com") # Instead of requests.get()
resp = frappe.make_post_request("https://api.com", data=payload)

Available Sandbox API (Complete Reference)

frappe.get_doc()

frappe.new_doc()

frappe.get_last_doc()

frappe.get_cached_doc()

frappe.get_mapped_doc()

frappe.rename_doc()

frappe.delete_doc()

frappe.db.get_list()

frappe.db.get_all()

frappe.db.get_value()

frappe.db.get_single_value()

frappe.db.set_value()

frappe.db.exists()

frappe.db.sql()

frappe.db.commit()

frappe.db.rollback()

frappe.db.escape()

frappe.qb

frappe.make_get_request()

frappe.make_post_request()

frappe.make_put_request()

frappe.utils.*

frappe.parse_json()

frappe.as_json()

frappe.session.user

frappe.get_roles()

frappe.has_permission()

frappe.throw()

frappe.msgprint()

frappe.log_error()

frappe.sendmail()

json

Script Type Selection Errors

ALWAYS verify you selected the correct Script Type:

doc

frappe.form_dict

/api/method/{method_name}

frappe.db.commit()

user

Common Mistake: Wrong Event

# ❌ WRONG — "After Save" cannot prevent save
# Script Type: Document Event, Event: After Save
if not doc.customer:
    frappe.throw("Customer is required")  # Document already saved!

# ✅ CORRECT — Use "Before Save" or "Before Validate"
# Script Type: Document Event, Event: Before Save
if not doc.customer:
    frappe.throw("Customer is required")  # Prevents save

Sandbox Workarounds

try/except Is Blocked: Use Conditional Checks

# ❌ BLOCKED in sandbox
try:
    customer = frappe.get_doc("Customer", doc.customer)
except Exception:
    frappe.throw("Customer not found")

# ✅ CORRECT — Check first, then access
if not frappe.db.exists("Customer", doc.customer):
    frappe.throw(f"Customer '{doc.customer}' not found")
customer = frappe.get_doc("Customer", doc.customer)

raise Is Blocked: Use frappe.throw()

# ❌ BLOCKED
if amount < 0:
    raise ValueError("Amount cannot be negative")

# ✅ CORRECT
if amount < 0:
    frappe.throw("Amount cannot be negative")

frappe.throw() Exception Types for API Scripts

frappe.ValidationError

frappe.PermissionError

frappe.DoesNotExistError

frappe.AuthenticationError

# API Script — Correct exception types
if not customer:
    frappe.throw("Customer param required", exc=frappe.ValidationError)  # 417
if not frappe.db.exists("Customer", customer):
    frappe.throw("Customer not found", exc=frappe.DoesNotExistError)    # 404
if not frappe.has_permission("Customer", "read", customer):
    frappe.throw("Access denied", exc=frappe.PermissionError)           # 403

Scheduler Script: Critical Mistakes

# ❌ WRONG — No limit, no commit, no error logging
invoices = frappe.get_all("Sales Invoice", filters={"status": "Unpaid"})
for inv in invoices:
    frappe.db.set_value("Sales Invoice", inv.name, "reminder_sent", 1)

# ✅ CORRECT — Limit, batch commit, error logging
BATCH_SIZE = 50
invoices = frappe.get_all(
    "Sales Invoice",
    filters={"status": "Unpaid", "docstatus": 1},
    fields=["name", "customer"],
    limit=500  # ALWAYS limit
)

errors = []
for i in range(0, len(invoices), BATCH_SIZE):
    batch = invoices[i:i + BATCH_SIZE]
    for inv in batch:
        if not frappe.db.exists("Customer", inv.customer):
            errors.append(f"{inv.name}: Customer not found")
            continue
        frappe.db.set_value("Sales Invoice", inv.name, "reminder_sent", 1)
    frappe.db.commit()  # REQUIRED

if errors:
    frappe.log_error("\n".join(errors), "Reminder Errors")
frappe.db.commit()

SQL Injection Prevention

# ❌ VULNERABLE — String interpolation with user input
territory = frappe.form_dict.get("territory")
conditions = f"`tabCustomer`.territory = '{territory}'"  # SQL INJECTION!

# ✅ SAFE — Use frappe.db.escape()
territory = frappe.form_dict.get("territory")
conditions = f"`tabCustomer`.territory = {frappe.db.escape(territory)}"

# ✅ SAFEST — Use parameterized query or Query Builder
results = frappe.db.get_all("Customer", filters={"territory": territory})

ALWAYS / NEVER Rules

ALWAYS

1. Use

   frappe.utils.*

   instead of Python imports — Only

   json

   module is importable
2. Use

   frappe.throw()

   instead of

   raise

   —

   raise

   is blocked by sandbox
3. Use conditional checks instead of

   try/except

   — Exception handling is blocked [v14-v15]
4. Call

   frappe.db.commit()

   in Scheduler scripts — Changes are NOT auto-committed
5. Add

   limit

   to ALL queries in Scheduler scripts — Prevent memory exhaustion
6. Set

   frappe.response["message"]

   in API scripts — Otherwise response is empty
7. Use

   frappe.db.escape()

   for user input in SQL — Prevent SQL injection
8. Log errors in Scheduler scripts with

   frappe.log_error()

   — No user to see errors
9. Verify Script Type matches your intent — Document Event vs API vs Scheduler

NEVER

1. NEVER use

   import

   statements (except

   json

   ) — Blocked by RestrictedPython
2. NEVER use

   try/except

   or

   raise

   — Blocked by sandbox [v14-v15]
3. NEVER call

   doc.save()

   in Before Save — Causes infinite recursion
4. NEVER use string formatting for SQL with user input — SQL injection risk
5. NEVER process unlimited records in Scheduler — Always use

   limit

6. NEVER assume

   doc

   exists in API/Scheduler scripts — Only available in Document Events
7. NEVER forget

   frappe.db.commit()

   in Scheduler — All changes will be lost

Reference Files

references/examples.md

references/anti-patterns.md

references/patterns.md