Troubleshooting

🔧 Common Issues & Solutions

Complete troubleshooting guide for RHDP Skills Marketplace.

🔌 Plugin-Based Installation Issues

Marketplace Shows "(no content)"

Symptom:

After adding marketplace, plugin list shows "(no content)"

Causes:

Old cached marketplace data
Plugin structure mismatch

Solution:

# Remove and re-add marketplace
/plugin marketplace remove rhdp-marketplace
/plugin marketplace add https://github.com/rhpds/rhdp-skills-marketplace

# Or force refresh
/plugin marketplace update

Skills Don't Show Namespace Prefix

Symptom:

Skills listed incorrectly without namespace prefix

Cause:

Old plugin version installed

Solution:

# Update marketplace
/plugin marketplace update

# Update plugins
/plugin update showroom@rhdp-marketplace
/plugin update agnosticv@rhdp-marketplace

# Restart Claude Code
# Exit completely and restart

SSH Clone Fails (Permission Denied)

Symptom:

Permission denied (publickey) when adding marketplace

Cause:

Using SSH format without SSH keys configured

Solution:

Use HTTPS instead:

/plugin marketplace add https://github.com/rhpds/rhdp-skills-marketplace

Skills Not Available After Installation

Symptom: Installed plugin but skills don’t appear in /help or /skills

Cause: Claude Code needs restart to load new plugins

Solution:

Exit Claude Code completely (not just close window)
Restart Claude Code
Verify: /skills

Unknown skill: showroom:create-demo

Symptom: Error message when trying to use /showroom:create-demo

Causes:

Plugin not installed
Old plugin version (without namespace support)
Claude Code not restarted after installation

Solution:

# Check installed plugins
/plugin list

# If not installed
/plugin install showroom@rhdp-marketplace

# If installed, update it
/plugin update showroom@rhdp-marketplace

# Restart Claude Code
# Exit and restart

Plugins Installed But Old Skills Still Appear

Symptom: Both old /showroom:create-lab and new /showroom:create-lab appear

Cause: Old file-based installation not removed

Solution:

# Remove old file-based skills
rm -rf ~/.claude/skills/create-lab
rm -rf ~/.claude/skills/create-demo
rm -rf ~/.claude/skills/blog-generate
rm -rf ~/.claude/skills/verify-content
rm -rf ~/.claude/skills/agnosticv-catalog-builder
rm -rf ~/.claude/skills/agnosticv-validator
rm -rf ~/.claude/skills/deployment-health-checker

# Restart Claude Code

Migration Issues

All Skills Deleted After Clean Install

Symptom: Removed old plugins but new ones don’t work

Cause: Forgot to reinstall marketplace plugins

Solution:

# Add marketplace (choose one)
# If you have SSH keys configured for GitHub
/plugin marketplace add rhpds/rhdp-skills-marketplace

# If SSH not configured, use HTTPS
/plugin marketplace add https://github.com/rhpds/rhdp-skills-marketplace

# Install plugins
/plugin install showroom@rhdp-marketplace
/plugin install agnosticv@rhdp-marketplace
/plugin install health@rhdp-marketplace

# Restart Claude Code

Want to Rollback to File-Based Installation

Symptom: Plugin system not working, need old installation

Solution:

See Migration Guide - Rollback

Plugin Update Issues

Update Shows No New Version Available

Symptom: /plugin marketplace update says no updates but you know there’s a newer version

Solution:

# Force remove and re-add marketplace
/plugin marketplace remove rhdp-marketplace
/plugin marketplace add https://github.com/rhpds/rhdp-skills-marketplace

# Reinstall plugins
/plugin install showroom@rhdp-marketplace --force

Plugin Cache Corrupted

Symptom: Plugins behaving strangely or skills missing

Solution:

# Completely remove plugins
/plugin uninstall showroom@rhdp-marketplace
/plugin uninstall agnosticv@rhdp-marketplace
/plugin uninstall health@rhdp-marketplace

# Remove marketplace
/plugin marketplace remove rhdp-marketplace

# Clear cache manually
rm -rf ~/.claude/plugins/cache/*
rm -rf ~/.claude/plugins/marketplaces/*

# Reinstall fresh
/plugin marketplace add https://github.com/rhpds/rhdp-skills-marketplace
/plugin install showroom@rhdp-marketplace

# Restart Claude Code

File-Based Installation Issues (Legacy)

⚠️

Note: File-based installation is deprecated. Please use plugin-based installation.

Installation Issues

Git Not Installed

Symptom: git: command not found

Solution:

# macOS
brew install git

# RHEL/Fedora
sudo dnf install git

# Ubuntu/Debian
sudo apt-get install git

Installation Fails Silently

Symptom: No errors but skills not installed

Solution:

# Run with verbose output
bash -x <(curl -fsSL https://raw.githubusercontent.com/rhpds/rhdp-skills-marketplace/main/install.sh)

# Check permissions
ls -la ~/.claude/
ls -la ~/.cursor/

Cannot Download Install Script

Symptom: curl: Could not resolve host

Solution:

Check internet connection
Verify GitHub is accessible
Try alternative installation:

# Clone and run locally
git clone https://github.com/rhpds/rhdp-skills-marketplace.git
cd rhdp-skills-marketplace
./install.sh

Skill Recognition Issues

Skill Not Found After Installation

Symptom: /showroom:create-lab not recognized in editor

Solution:

Restart your editor (most common fix)

Verify installation:

ls ~/.claude/skills/create-lab
ls ~/.cursor/skills/create-lab

Check version file:

cat ~/.claude/skills/.rhdp-marketplace-version

Reinstall if needed:

curl -fsSL https://raw.githubusercontent.com/rhpds/rhdp-skills-marketplace/main/install.sh | bash

Wrong Namespace Installed

Symptom: /agnosticv:catalog-builder not found but /showroom:create-lab works

Solution:

This is expected - you installed only showroom namespace. To add agnosticv skills:

curl -fsSL https://raw.githubusercontent.com/rhpds/rhdp-skills-marketplace/main/install.sh | \
  bash -s -- --namespace agnosticv

Or install all:

curl -fsSL https://raw.githubusercontent.com/rhpds/rhdp-skills-marketplace/main/install.sh | \
  bash -s -- --namespace all

Skills Installed for Wrong Platform

Symptom: Skills in ~/.claude/ but using Cursor

Solution:

Reinstall for correct platform:

curl -fsSL https://raw.githubusercontent.com/rhpds/rhdp-skills-marketplace/main/install.sh | \
  bash -s -- --platform cursor --namespace all --force

Showroom Skill Issues

create-lab Generates Invalid AsciiDoc

Symptom: Showroom build fails with AsciiDoc errors

Solution:

Run verification:
```
/verify-content
```
Fix reported syntax errors
Common issues:
- Missing blank lines before code blocks
- Unclosed attributes {}
- Invalid heading levels

Attributes Not Rendering

Symptom: {openshift_console_url} shows as literal text

Solution:

Ensure _attributes.adoc is defined:

// content/modules/ROOT/partials/_attributes.adoc
:openshift_console_url: https://console.example.com
:user: user1
:password: openshift

And referenced in pages:

// At top of module file
include::partial$_attributes.adoc[]

verify-content Reports Many Issues

Symptom: Long list of warnings and errors

Solution:

Fix errors first (blocking issues)
Address warnings (best practices)
Review suggestions (optional improvements)
Re-run /showroom:verify-content after each batch of fixes

blog-generate Produces Poor Quality

Symptom: Generated blog post lacks structure or clarity

Solution:

Ensure workshop content is complete and high-quality
Review Know/Show structure in lab modules
Run /showroom:verify-content on lab first
Try /showroom:blog-generate again after improving lab content

AgnosticV Skill Issues

agnosticv-catalog-builder Can’t Find Repository

Symptom: AgnosticV repository not found at ~/work/code/agnosticv

Solution:

Clone the repository:

cd ~/work/code
git clone git@github.com:rhpds/agnosticv.git

Verify access:

cd agnosticv
git status

UUID Already Exists

Symptom: UUID collision detected

Solution:

Generate new UUID:

# macOS/Linux
uuidgen

# Python
python -c "import uuid; print(uuid.uuid4())"

Update common.yaml:

__meta__:
  asset_uuid: <new-uuid-here>

Workload Collection Not Found

Symptom: Collection <name> not available in requirements

Solution:

Check collection name spelling

Verify collection version exists:

ansible-galaxy collection list <namespace>.<collection>

Check AgnosticD core_workloads repository
Update requirements_content.collections in common.yaml

agnosticv-validator Reports Many Errors

Symptom: Validation fails with multiple errors

Solution:

Read error messages carefully
Fix ERRORS first (blocking deployment)
Address WARNINGS (best practices)
Consider SUGGESTIONS (optional)
Re-validate after each fix:
```
/agnosticv-validator
```

Cannot Push to Remote

Symptom: Permission denied (publickey) or remote: Repository not found

Solution:

Verify SSH key setup:
```
ssh -T git@github.com
```
Check remote URL:
```
git remote -v
```

Update remote if needed:

git remote set-url origin git@github.com:rhpds/agnosticv.git

RHDP Integration Issues

Catalog Not Found in RHDP

Symptom: Cannot find catalog after pushing to Git

Solution:

Verify PR is merged to main branch
Wait 5-10 minutes for sync
Check catalog slug matches directory name
Verify __meta__.catalog.display_name is set

Deployment Fails in RHDP

Symptom: Service fails to deploy

Solution:

Check Events tab in RHDP service
Look for error messages
Common issues:
- Invalid UUID
- Missing workload collection
- Infrastructure not available
- Workload configuration errors
Fix issues in Git and redeploy

UserInfo Variables Not Available

Symptom: Cannot find UserInfo after deployment

Solution:

Wait for deployment to complete (check status)
Go to service Details → Advanced settings
Look for user_info_messages section
If missing, check workload configurations for agnosticd_user_info tasks

Update Issues

Update Script Shows “Already Latest”

Symptom: Update says latest version but you know there’s a newer one

Solution:

Force update:

curl -fsSL https://raw.githubusercontent.com/rhpds/rhdp-skills-marketplace/main/update.sh | \
  bash -s -- --force

Update Fails Mid-Installation

Symptom: Update starts but doesn’t complete

Solution:

Check internet connection

Restore from backup:

ls ~/.claude/skills-backup-*/
cp -r ~/.claude/skills-backup-<timestamp>/* ~/.claude/skills/

Try fresh installation:

curl -fsSL https://raw.githubusercontent.com/rhpds/rhdp-skills-marketplace/main/install.sh | bash

Platform-Specific Issues

macOS: Permission Denied

Symptom: Permission denied when installing

Solution:

# Check ownership
ls -la ~/.claude/
ls -la ~/.cursor/

# Fix ownership if needed
sudo chown -R $USER:staff ~/.claude/
sudo chown -R $USER:staff ~/.cursor/

macOS: Gatekeeper Blocks Execution

Symptom: “cannot be opened because it is from an unidentified developer”

Solution:

Scripts are safe, but if blocked:

# Run with bash explicitly
bash <(curl -fsSL https://raw.githubusercontent.com/rhpds/rhdp-skills-marketplace/main/install.sh)

Linux: Home Directory Not Standard

Symptom: Installation fails because skills directory not found

Solution:

Set HOME explicitly:

HOME=/custom/home/path bash <(curl -fsSL https://raw.githubusercontent.com/rhpds/rhdp-skills-marketplace/main/install.sh)

Getting Help

Before Asking for Help

Check this troubleshooting guide
Search GitHub Issues: Existing issues
Gather information:
- Platform (Claude Code or Cursor)
- Version installed
- Error messages (full text)
- Steps to reproduce

How to Get Help

GitHub Issues: Create new issue

Slack:

#forum-demo-developers - RHDP questions and support

Include in Your Request:

Platform: Claude Code / Cursor
Version: (from ~/.claude/skills/.rhdp-marketplace-version)
Namespace: showroom / agnosticv / all
Issue: Brief description
Error Message: Full error text
Steps to Reproduce: What you did before the error

Known Issues

Issue: Skills Load Slowly

Status: Known limitation

Workaround: First invocation may be slow; subsequent calls are faster

Issue: Validation Takes Time on Large Catalogs

Status: Expected behavior

Workaround: Use validation scope selection (quick vs full)

Debug Mode

For advanced troubleshooting:

# Installation debug
bash -x <(curl -fsSL https://raw.githubusercontent.com/rhpds/rhdp-skills-marketplace/main/install.sh)

# Check file permissions
ls -laR ~/.claude/skills/
ls -laR ~/.cursor/skills/

# Verify Git configuration
git config --list

# Check Python availability (for UUID generation)
python --version
python3 --version