The kernel logs viewer in Kernel Logs Viewer is the right starting point for most troubleshooting — it streams the live logs in your browser and is enough to diagnose the majority of init-script and dependency failures. This article is what you reach for when the viewer doesn't have what you need: it lays out every log file the kernel writes, gives you small snippets to verify a JAR or Python package landed where you expected, and lists the most common failure modes with their fix.
The log files
Each layer of init script and dependency setup writes its output to a separate log file under /logs/ on the kernel pod. The files are written by the bootstrap script and the kernel itself; the kernel logs viewer reads from them.
| Path | What's in it |
|---|---|
| /logs/global_init_script.log | Output of the global init script (admin-set in Platform Settings). |
| /logs/global_init_configs.log | Output of the auto-generated global dependency script (downloads JARs, pip installs from global Spark configs). |
| /logs/notebook_init_script.log | Output of the notebook-specific init script (set from the toolbar editor). |
| /logs/runtime_init_script.log | Output of the runtime template's init script (admin-set on the runtime template). |
| /logs/runtime_init_configs.log | Output of the auto-generated runtime dependency script (JARs and pip installs from runtime Spark configs). |
| /logs/syntasa_kernel.log | Aggregated stream of all of the above plus the kernel's own boot output. This is what the viewer's Bootstrap tab shows. |
| /logs/spark_driver.log | Spark driver / JVM logs (log4j2 rolling file). This is what the viewer's Spark tab shows. |
Did the init script even run?
Each init script is staged on the kernel pod as a file under /tmp/ before being sourced. If you suspect a script wasn't picked up at all, look for these files — if the corresponding .sh doesn't exist, the script wasn't found and never ran. If it does exist but the matching .log is empty, it ran but produced no output (which usually means it succeeded silently).
- /tmp/global_init_script.sh
- /tmp/global_init_configs.sh
- /tmp/notebook_init_script.sh
- /tmp/runtime_init_script.sh
- /tmp/runtime_init_configs.sh
Verifying a JAR is on the classpath
After an init script runs that was supposed to put a JAR onto the Spark classpath (whether via syntasa.jar.dependencies.*, spark.jars, or a manual wget into $SPARK_HOME/jars/), the simplest way to confirm is to load a class from the JAR:
python
# Python — load a class from the JAR you expect on the classpath
spark._jvm.Class.forName("org.sqlite.JDBC")
scala
// Scala
Class.forName("org.sqlite.JDBC")
If the call returns without raising ClassNotFoundException, the JAR is loaded. If it raises, the JAR isn't on the classpath — start with /logs/global_init_configs.log or /logs/runtime_init_configs.log to find out why the download didn't land.
Verifying a Python package on every executor
The driver having a Python package installed isn't the same as the executors having it. To confirm a package is reachable on every executor, force a per-partition import via Spark:
python
spark.sparkContext.parallelize(range(4), 4) \
.mapPartitions(lambda _: [__import__("humanize").__version__]) \
.collect()If the package is on every executor, you'll get back a list of the version string with one entry per partition. If it isn't, the call raises ModuleNotFoundError — start with /logs/global_init_configs.log or /logs/runtime_init_configs.log.
The SYNTASA_DEP_ERROR pattern
When the auto-generated dependency script fails to download or install a dependency, it prints a line beginning with SYNTASA_DEP_ERROR: describing the failure. Search for that token in the global or runtime dependency logs to find the exact failure point — there will be a separate SYNTASA_DEP_ERROR line per failed dependency.
What you'll see
SYNTASA_DEP_ERROR: Failed to download spark.jars entry: {path} · SYNTASA_DEP_ERROR: Failed to pip install: {package} · SYNTASA_DEP_ERROR: Failed to download Maven dependency: {coord}Common issues and fixes
| Symptom | What's likely wrong | Fix |
|---|---|---|
| Global dependency script not found | Globally-declared dependencies didn't install — Spark configs are misplaced in Platform Settings (under notebookConfig instead of runtimeConfig > sparkConfig). | Admin task — ask your platform admin to move the configs into runtimeConfig > sparkConfig in Platform Settings. |
| Runtime dependency script not found | The runtime template either has no Spark configs or wasn't properly attached. | Open the kernel logs viewer ( Kernel Logs Viewer) and look in the Bootstrap tab for the runtime attach lines. If the attach didn't happen, re-attach from the runtime toolbar; if it did but no dependencies ran, the template needs Spark configs added (admin task). |
| Python package missing on executors | The dependency script failed silently, or the network can't reach PyPI from the executor. | Check /logs/global_init_configs.log or /logs/runtime_init_configs.log for SYNTASA_DEP_ERROR lines. Verify outbound connectivity to PyPI from the executor environment. |
| JARs not on the classpath (declared via syntasa.jar.dependencies.* or spark.jars) | Auto-generated dependency script failed to download or copy the JAR. | Search /logs/global_init_configs.log or /logs/runtime_init_configs.log for SYNTASA_DEP_ERROR lines. Confirm $SPARK_HOME/jars/ on the driver. |
| JARs not on the classpath (downloaded by hand-written wget in your init script) | Your wget call failed (404, network error) and the kernel boot continued anyway. | Check /logs/notebook_init_script.log, /logs/runtime_init_script.log, or /logs/global_init_script.log for the wget output. Add set -e to the top of your init script if you want a download failure to fail the kernel boot. |
| spark.jars config seems ignored | Intentional: spark.jars cloud paths are downloaded into $SPARK_HOME/jars/ and stripped from SparkConf. | Don't add a spark.jars entry — the JAR is already on the classpath. Use the verification snippet above to confirm. |
| Offline dependencies fail to download | Files aren't where the platform expects them, or the bucket isn't readable. | Verify files are at {bucket}/{configFolder}/deps/python/ or {bucket}/{configFolder}/deps/jars/. Check the kernel pod's IAM permissions. On high-side AWS, verify the custom S3 endpoint is configured. |
If your kernel pod restarted before you could read the logs
The kernel logs viewer reads from inside the live kernel pod — once the pod restarts, those log files are gone. If a bootstrap failure caused your kernel to crash and respawn, you can't read the failure logs from the new pod's viewer. In that case, ask your admin: the platform's pod log retention may have captured the failed pod's stdout/stderr at the cluster level, and an admin can pull those out for you.
Related sections
- Init Scripts & Dependencies. The layered global / runtime / notebook model and what each layer is for. When the troubleshooting table above tells you to fix a Spark config, this is the article that tells you where to put it.
- Kernel Logs ViewerThe browser-based viewer that streams /logs/syntasa_kernel.log (Bootstrap tab) and /logs/spark_driver.log (Spark tab). Start there before reaching for the file-by-file paths in this article.