A.3. Troubleshooting

Login Problems

Token Authentication Fails

Symptoms:

• The error message "A token is required"
• The error message "Invalid token"
• Returning to the login page straight after signing in

Causes:

• Using an expired token
• A malformed token
• A token without enough rights

What to do:

1. Obtain a new token

   # create a Karmada token
   kubectl -n karmada-system get secret karmada-console-secret -o jsonpath='{.data.token}' | base64 -d

2. Check the token format

   • Check the token was copied correctly
   • Check no leading or trailing whitespace is included
   • Check the whole token was copied

3. Check the token's rights

   # check the ClusterRole
   kubectl get clusterrolebinding -o wide | grep console

SSO Login Fails

Symptoms:

• It sticks on the "Initialising SSO..." screen
• An error after pressing the SSO login button
• The Keycloak redirect fails

Causes:

• The Keycloak server cannot be reached
• Keycloak is misconfigured
• A browser cookie or session problem

What to do:

1. Check the Keycloak server

   # check the Keycloak service
   kubectl get pods -n keycloak

2. Clear the browser cache

   • Clear the browser cookies and cache
   • Try an incognito or private window

3. Check the Keycloak configuration

   • Check the realm and client settings
   • Check the redirect URI setting

The Session Expires

Symptoms:

• Suddenly taken to the login page
• A 401 error on an API request
• The message "The credentials have expired"

What to do:

1. Refresh the page and sign in again
2. Obtain a new token and sign in again
3. Try signing in from an incognito window

---

Cluster Connection Problems

A Cluster Is NotReady

Symptoms:

• "NotReady" shown in the cluster list
• A red warning on the cluster card
• That cluster's resources cannot be read

Causes:

• A network problem reaching the member cluster
• A problem with the member cluster's agent
• The control plane certificate has expired

What to do:

1. Check the network connection

   # test the connection to the member cluster from the control plane
   kubectl --kubeconfig=/path/to/member/kubeconfig cluster-info

2. Check the Karmada agent

   # check the agent on the member cluster
   kubectl -n karmada-system get pods -l app=karmada-agent
   kubectl -n karmada-system logs -l app=karmada-agent --tail=50

3. Check the cluster state in detail

   # check the cluster state on the Karmada control plane
   kubectl get cluster <cluster-name> -o yaml

A Cluster Does Not Appear in the List

Symptoms:

• A newly registered cluster is not shown
• There are fewer clusters than expected

Causes:

• The registration did not complete
• The clusters cannot be read for want of rights
• An API caching problem

What to do:

1. Check the registration

   # list the registered clusters
   kubectl get clusters

2. Refresh the page

   • Refresh the browser or press the refresh button

3. Check the rights

   • Check the token in use has the right to read clusters

---

Policy Problems

A Propagation Policy Does Not Apply

Symptoms:

• The resource is not propagated after creating the PropagationPolicy
• The binding stays "Pending"
• It does not propagate to one particular cluster

Causes:

• The resource selector does not match the resource
• The cluster affinity is wrong
• The target cluster is NotReady

What to do:

1. Check the resource selector

   • Check the API version, kind, and name are right
   • Check the namespace matches
   • Check the label selector is right

2. Check the policy conditions

   • Check the "Conditions" tab on the policy detail page
   • Look for conditions in the False state
   • Read the error message

3. Check the binding

   # check the ResourceBinding
   kubectl get resourcebinding -n <namespace>
   kubectl describe resourcebinding <name> -n <namespace>

4. Check the Work resource

   # check the Work resource
   kubectl get work -n karmada-es-<cluster-name>

An Override Policy Does Not Apply

Symptoms:

• The resource is unchanged after creating the OverridePolicy
• The override does not apply on one particular cluster

Causes:

• The resource selector does not match the resource
• The cluster affinity is wrong
• The overrider is misconfigured

What to do:

1. Check the overrider

   • Check the overrider type and path are right
   • Check the JSON patch format is right

2. Check the policy priority

   • Where several policies apply to the same resource, check the priority
   • A ClusterOverridePolicy wins over an OverridePolicy

3. Check the resource on the member cluster

   # check the actual resource on the member cluster
   kubectl --kubeconfig=/path/to/member/kubeconfig get <resource> <name> -o yaml

Resources Remain After the Policy Is Deleted

Symptoms:

• The resource is still on the member cluster after the PropagationPolicy is deleted
• An unwanted resource stays in place

Causes:

• PreserveResourcesOnDeletion is enabled
• The delete has not finished

What to do:

1. Check the policy setting

   • Check the preserveResourcesOnDeletion value
   • Check whether keeping the resource was intended

2. Delete by hand

   # delete the resource on the member cluster by hand
   kubectl --kubeconfig=/path/to/member/kubeconfig delete <resource> <name>

---

Workload Problems

Pod Error States

The common pod error states:

State	Description	What to do
ImagePullBackOff	The container image cannot be fetched	Check the image name and the registry access rights
ErrImagePull	The image pull failed	Check the image exists and the network is reachable
CrashLoopBackOff	The container keeps crashing	Check the container logs and fix the application error
OOMKilled	Ended for want of memory	Raise the memory limit or fix the memory leak
Pending	Waiting to be scheduled	Check the node resources and the node selector
CreateContainerConfigError	The container configuration is wrong	Check the ConfigMap and Secret references

How to diagnose:

1. Check the pod events

   • Check the "Events" tab on the pod detail page in the MCM console

2. Check the container logs

   # check the pod logs
   kubectl logs <pod-name> -n <namespace>
   
   # check the previous container's logs (for CrashLoopBackOff)
   kubectl logs <pod-name> -n <namespace> --previous

The Deployment Replica Count Does Not Match

Symptoms:

• The desired and actual replica counts differ
• Replicas are created on only some clusters

Causes:

• Node resources are short
• Scheduling constraints
• A problem with the replica scheduling strategy

What to do:

1. Check the node resources

   • Check the resource usage per cluster on the Overview page
   • Check the allocatable resources on the node detail page

2. Check the scheduling strategy

   • Check the replicaScheduling setting on the PropagationPolicy
   • Review the Duplicated against Divided strategy

3. Check the events

   • Check the Events tab on the Deployment detail page
   • Look for scheduling error messages

---

UI and Screen Problems

A Page Does Not Load

Symptoms:

• A blank screen, or the loading state persists
• An error page is shown
• Only some components appear

What to do:

1. Refresh the page

   • Refresh with F5 or Ctrl/Cmd + R
   • A hard refresh: Ctrl/Cmd + Shift + R

2. Clear the browser cache

   • Clear the cache and cookies in the browser settings
   • Clear only this site's data, so other sites are unaffected

3. Check the browser console

   • Open the developer tools with F12
   • Read the error messages on the Console tab

4. Try another browser

   • Test in Chrome, Firefox, Edge, or another browser

The Theme Does Not Apply

Symptoms:

• Still light mode after choosing dark mode
• The theme applies only in part
• Following the system theme does not work

What to do:

1. Apply the setting again

   • On the Settings page, change the theme to another value and back to the one you want

2. Check local storage

   • Browser developer tools → Application → Local Storage
   • Check the MCM data is stored there

3. Refresh the page

   • A hard refresh reloads the cached styles

The Topology Is Slow or Freezes

Symptoms:

• The topology map takes a long time to load
• Dragging and zooming are slow
• The browser stops responding

Causes:

• Too many nodes are shown
• The browser is short of memory
• Hardware acceleration is off

What to do:

1. Lower the node limit

   • Settings → Topology → set Maximum Nodes per Resource Type to a low value (5 to 10)

2. Use the filters

   • Choose one namespace or cluster
   • Show only the resource types you need

3. Turn on browser hardware acceleration

   • Turn on "Use hardware acceleration" in the browser settings

4. Close other tabs and programs

   • Close what you do not need to free up system resources

Search Does Not Work

Symptoms:

• No results after typing a search term
• The search box will not take focus
• The / shortcut does not work

What to do:

1. Check the focus

   • A shortcut does not work while another input field has focus
   • Click outside the input field and try / again

2. Check the browser extensions

   • Some extensions intercept keyboard shortcuts
   • Test in an incognito window

3. Click the search box directly

   • Click the search icon on the top navigation

---

API Errors

401 Unauthorized

Symptoms:

• The error "Not authenticated"
• Every API request fails
• A red error notification

What to do:

1. Log out and sign in again
2. Obtain a new token and sign in again
3. Clear the browser's local storage and try again

403 Forbidden

Symptoms:

• The error "You do not have permission"
• Only a particular resource cannot be reached

What to do:

1. Check the rights

   • Check the ClusterRole/Role of the token in use
   • Grant the rights needed for that resource

2. Ask an administrator

   • Request a change to the RBAC settings

500 Internal Server Error

Symptoms:

• A server error message
• An error when performing a particular action

What to do:

1. Try again

   • It may be a passing error, so wait a moment and retry

2. Check the API server

   # check the Karmada API server
   kubectl -n karmada-system get pods -l app=karmada-apiserver
   kubectl -n karmada-system logs -l app=karmada-apiserver --tail=50

3. Ask an administrator

   • The server logs need checking

Network Errors

Symptoms:

• A "network error" or "connection failed" message
• The connection drops intermittently

What to do:

1. Check the network

   • Check the internet connection
   • Check the VPN connection

2. Check the server is reachable

   # test reaching the MCM API server
   curl -k https://<mcm-api-server>/healthz

3. Check the firewall and proxy

   • Check the ports needed are open
   • Check the proxy settings

---

Data and Display Problems

Stale Data Is Shown

Symptoms:

• A resource just created is not visible
• A deleted resource is still shown
• The status does not update

What to do:

1. Refresh

   • Press the page's refresh button
   • Refresh the browser

2. Check the cache

   • The API response may have been cached
   • Try a hard refresh

The Numbers Do Not Add Up

Symptoms:

• The Overview figures differ from the actual resource counts
• The per-cluster totals do not match

Causes:

• The data has not synchronised yet
• Some clusters have a connection problem
• A filter is applied

What to do:

1. Check the filters

   • Check whether a namespace or cluster filter is applied
   • Clear every filter and look again

2. Check the clusters

   • Check every cluster is Ready
   • Data from a NotReady cluster may be inaccurate

3. Refresh the page

   • Update to the latest data

---

Resource Creation and Editing Problems

The Create Button Is Disabled in the Dialog

Symptoms:

• Every field is filled in but the create button stays disabled
• Nothing is marked as required, yet it cannot be created

Causes:

• A required field is missing
• Validation failed
• The name is a duplicate

What to do:

1. Check every field

   • Check the namespace is chosen
   • Check the policy name is entered
   • Check the target resources are chosen
   • Check the target clusters are chosen

2. Check for a duplicate name

   • Check whether a policy of the same name already exists

3. Check the format

   • The name may use only lowercase letters, numbers, and hyphens
   • Special characters cannot be used

YAML Editing Errors

Symptoms:

• An error when saving the YAML
• The message "Invalid YAML"

What to do:

1. Check the YAML syntax

   • Check the indentation is right (2 or 4 spaces, used consistently)
   • Use spaces, not tabs

2. Check the required fields

   • Check apiVersion, kind, metadata and the other required fields are present

3. Validate the YAML

   • Use an online YAML validator
   • Validate locally with kubectl apply --dry-run=client

---

Browser Compatibility

Supported Browsers

Browser	Minimum version	Status
Google Chrome	90+	Fully supported
Microsoft Edge	90+	Fully supported
Firefox	88+	Fully supported
Safari	14+	Fully supported
Internet Explorer	-	Not supported

Browser-Related Problems

Symptoms:

• The problem happens in one browser only
• The layout is broken
• A feature does not work

What to do:

1. Update the browser

   • Update to the latest version

2. Disable the extensions

   • Turn off ad-blocking and security extensions for a moment

3. Use another browser

   • Chrome is recommended

---

Gathering Diagnostic Information

When asking an administrator for help, this information is useful:

The Basics

1. The MCM Console version

   • Settings page → the About Product section

2. The browser

   • The browser and its version
   • The operating system

3. The error message

   • The exact text of the error message
   • When it happened and what you were doing

The Browser Console Log

1. Open the developer tools with F12
2. Choose the Console tab
3. Capture the error (red) and warning (yellow) messages
4. Check the failed requests on the Network tab

Screenshots

1. Capture the error screen
2. Describe what happened before and after

---

Related Documents

• Login
• UI Overview
• Settings (User Settings)
• Shortcuts and Tips
• Glossary

---