MAS (Matrix Authentication Service) integration fails with multiple errors - image not found, PVC issues, and MSC3861 configuration errors

[oazabir]

Environment

• Chart: small-hack/matrix v21.2.0
• Kubernetes: microk8s
• MAS Chart Version: Using default from
  matrix chart v21.2.0
• Date: November 22, 2025

Summary

Attempting to enable MAS with upstream OAuth2
(Google) provider results in multiple
cascading failures that prevent successful
deployment. The integration appears broken
due to outdated image references,
configuration issues, and resource management
problems.

Steps to Reproduce

1. Start with working Matrix installation
   (chart v21.2.0)
2. Enable MAS in values.yaml:

  mas:
    enabled: true

    mas:
      database:
        uri: "postgresql://matrix:password@matr
  ix-postgres-rw:5432/matrix"

      upstream_oauth2:
        providers:
          - id: "01JCQXRM8KGOOGLE000000001"
            issuer:
  "https://accounts.google.com"
            client_id: "<google-client-id>"
            client_secret: "<google-secret>"
            token_endpoint_auth_method:
  "client_secret_post"
            scope: "openid email profile"
            discovery_mode: "oidc"
            claims_imports:
              subject:
                template: "{{ user.sub }}"
              localpart:
                template: "{{ 
  user.email.split('@')[0] }}"

3. Run helm upgrade

Expected Behavior

• MAS pod should start successfully
• Synapse should integrate with MAS via
  MSC3861
• OAuth2 authentication should be available

Actual Behavior

Issue 1: Image Not Found

Failed to pull image "ghcr.io/matrix-org/matr
ix-authentication-service:1.4.1":
rpc error: code = NotFound desc = failed to
pull and unpack image
"ghcr.io/matrix-org/matrix-authentication-ser
vice:1.4.1":
failed to resolve reference "ghcr.io/matrix-o
rg/matrix-authentication-service:1.4.1":
ghcr.io/matrix-org/matrix-authentication-serv
ice:1.4.1: not found

Root Cause:

• The chart's appVersion references image tag
  1.4.1 which doesn't exist
• MAS repository was archived September 10,
  2024
• Only available tags are: main, sha-162119d,
  main-debug
• Last image was published ~1 year ago

Issue 2: Missing claims_imports.subject
Template

First attempt without subject claim:
Error: UPGRADE FAILED: template:
matrix/charts/mas/templates/initial-config-se
cret.yaml:165:43:
executing "matrix/charts/mas/templates/initia
l-config-secret.yaml" at
<.claims_imports.subject.template>: nil
pointer evaluating interface {}.template

Root Cause: Chart template requires
claims_imports.subject but this isn't
documented in values schema

Issue 3: Synapse Init Container Failure

When MSC3861 experimental features are
enabled:
Error: yaml: control characters are not
allowed
Back-off restarting failed container
add-secret-values-to-config

Root Cause: The experimental_features.msc3861
configuration generates invalid YAML in
Synapse config

Issue 4: PVC Immutable Spec Error

Error: UPGRADE FAILED: cannot patch
"matrix-kahf-mas-config" with kind
PersistentVolumeClaim:
PersistentVolumeClaim
"matrix-kahf-mas-config" is invalid: spec:
Forbidden:
spec is immutable after creation except
resources.requests and
volumeAttributesClassName for bound claims
core.PersistentVolumeClaimSpec{
... // 2 identical fields
Resources: {Requests: {s"storage":
{i: {...}, s: "500Mi", Format:
"BinarySI"}}},
VolumeName:
"pvc-f0457532-0b32-43d0-b233-285e0c1554ba",

• StorageClassName: &"microk8s-hostpath",

• StorageClassName: nil,
  VolumeMode: &"Filesystem",
  DataSource: nil,
  ... // 2 identical fields
  }

Root Cause: Chart attempts to modify PVC
storageClassName from microk8s-hostpath to
nil after creation, which is forbidden

PVC gets stuck in Terminating state and
requires manual finalizer removal:

kubectl patch pvc -n matrix
matrix-kahf-mas-config -p
'{"metadata":{"finalizers":null}}'

Attempted Workarounds

Workaround 1: Override Image Tag

  mas:
    enabled: true
    image:
      tag: "main"  # Use available tag instead 
  of default 1.4.1

Result: Partially successful - image pulls,
but other errors persist

Workaround 2: Remove MSC3861 Configuration

Commenting out experimental_features fixes
Synapse init errors but breaks MAS
integration

experimental_features:

msc3861:

enabled: true

Workaround 3: Manual PVC Cleanup

kubectl delete pvc -n matrix
matrix-kahf-mas-config

Wait for termination, then remove

finalizers if stuck
kubectl patch pvc -n matrix
matrix-kahf-mas-config -p
'{"metadata":{"finalizers":null}}'

Helm Release History

REVISION STATUS DESCRIPTION
4 deployed Upgrade complete
(without MAS)
5 failed MAS image not found
6 failed PVC immutable spec
error
7 failed PVC immutable spec
error

Proposed Solutions

1. Update Chart appVersion: Change default
   MAS image tag from 1.4.1 to main or make it
   explicitly configurable
2. Fix PVC Template: Ensure PVC
   storageClassName doesn't change between helm
   releases
3. Add Documentation:
   - Document required claims_imports fields
   - Add example working configuration
   - Note MAS project archived status
4. Consider Deprecation: Given MAS is
   archived, consider:
   - Deprecating MAS subchart
   - Recommending Synapse's native OIDC
   instead
   - Adding migration guide