Troubleshooting for on-premise

This document provides an overview of common problems and strategies to either resolve issues or help debug them accordingly.

 

Applications are stuck during creation

Last updated	25 Jun 2025
Version (retroactively)	2025.19

Context

The application will not complete the creation process and will remain stuck on one of the steps. Common causes for this are:

1. Missing DNS records required for the application
2. Inability to communicate with other service(s) within the platform.
3. Duplicate name usage after an incomplete removal of an application.

 

Resolutions steps

Remove the application by hand

1. Open a console on the Synapse container.
   
   kubectl exec -it synapse-c95fd96b4-4mq5m
2. Open a remote console within the Synapse container
   
   bin/synapse remote
3. Remove the application
   

   Where $ID refers to the control panel ID of the application.

# Retrieve the application.
application = Synapse.Repo.get(Synapse.Schema.Application, $ID)

# Assign a standard user to perform the delete with.
user = Synapse.Repo.get(Synapse.Schema.User, 1)

# Remove the application by hand.
Synapse.Application.Deleter.delete(application, user)

 

Automatically restarts containers

Last updated	25 Jun 2025
Version(s)	2025.19

Context

Some containers within the platform can experience some variations in locking up the container. For example, by reserving too much memory and refusing to restart, or by overloading queues and being unable to process them unless prompted to drop some queues first.

Resolutions steps

Ensure your cluster respects the Kubernetes resource limitations and restarts containers accordingly when they’re reaching their memory threshold.

Resources:
 Limits:
  Cpu: 500m
  Memory: 500Mi
requests:
  Cpu: 100m
  Memory: 100Mi

Alternatively, you could use external metrics to create a warning or notification that can be acted on (automatically) to remove the containers.

Compiling components by hand

 

Last updated	25 jun 2025
Version(s)	2025.19

Context

Pages or actions might sometimes be unable to compile themselves; to further debug the origin of the problem, being able to compile these by hand can provide a lot of information.

Resolution steps

Pages:

V1:

1. Open a console on the meta pod.
   kubectl exec -it meta-api-5f9cdcb988-w2lr8
2. Open a remote console on the meta pod.
   bin/meta_api remote
3. Compile the pages by hand.
   Where $UUID is the UUID of the application you want to compile the pages for.

   uuid = "$UUID"
   endpoints = MetaAPI.Endpoints.all_with_pages(uuid)
   # Compile the artifact.
   MetaAPI.Services.PageArtifactCompiler.compile(uuid)
   # Compile each page.
   Enum.each(endpoints, fn %{id: id} -> 
     MetaAPI.Services.PageCompiler.compile(uuid, id)
   end)

V2:

1. Open a console on the pages compiler pod.
   kubectl exec -it pages-compiler-c676bf87c-tmk44
2. Compile the pages by hand.
   Where $UUID is the UUID of the application you want to compile the pages for.
   bun run compile $UUID

Actions:

1. Open a console on the actions compiler pod.
   kubectl exec -it actions-compiler-665d85c59d-zndh5
2. Open a remote console within the actions compiler container.
   bin/server remote
3. Compile the actions by hand.
   Where $UUID is the UUID of the application you want to compile the actions for.
   ActionsCompiler.compile($UUID)