Skip to main content
Version: 2.0.0

Troubleshooting

This guide covers common problems encountered when installing, configuring, and running yStore on Craft CMS 5. Issues are grouped by when they typically occur.

If your issue is not listed here, check the yStore GitHub Discussions or contact support@yui.sk.

Installation Issues​

Composer authentication fails​

Symptom

composer require yui/craft-plugin returns a 401 Unauthorized or Could not find package error.

Cause: Your auth.json file is missing, in the wrong location, or contains incorrect credentials.

Solution:

  1. Confirm auth.json exists in your project root (same directory as composer.json).
  2. Verify the credentials match exactly what is shown in your license dashboard at yui.sk.
  3. Check the repository URL is correct in composer.json:
{
    "repositories": {
        "ystore": {
            "type": "composer",
            "url": "https://composer.yui.sk"
        }
    }
}
  1. Test authentication directly:
composer config --list | grep yui
tip

If you recently rotated your credentials, clear Composer's cache before retrying: composer clear-cache

Migrations fail on install​

Symptom

php craft plugin/install ystore fails with a database error, migration exception, or silent rollback.

Cause 1 — Insufficient database privileges. The database user does not have CREATE TABLE or ALTER TABLE rights.

Solution: Grant the required privileges:

GRANT CREATE, ALTER, DROP, INDEX ON your_database.* TO 'craft_user'@'localhost';
FLUSH PRIVILEGES;

Cause 2 — Conflicting plugin. Another plugin has already created a table with the same name, or an old partial yStore install left orphaned tables.

Solution:

  1. Check for leftover tables from a previous install attempt:
php craft ystore/validate
  1. If orphaned tables are found, drop them manually or run:
php craft migrate/all
  1. Then retry the plugin install.
tip

Always run php craft migrate/all before installing yStore to ensure Craft itself is fully migrated.

Control Panel Issues​

yStore menu doesn't appear in the CP sidebar​

Symptom

After installation, there is no yStore section in the Craft Control Panel sidebar.

Cause: The plugin was downloaded via Composer but not installed and activated in Craft.

Solution:

  1. Confirm the plugin appears in Craft's plugin list:

    • Go to Settings → Plugins in the Craft CP.
    • Look for yStore in the list. If it shows as "Not installed", click Install.

  2. If it does not appear at all, run the install command manually:

php craft plugin/install ystore
  1. Check that the plugin is enabled (toggle is on) in Settings → Plugins.
tip

After enabling the plugin, do a hard refresh (Ctrl+Shift+R / Cmd+Shift+R) to clear any cached CP navigation state.

Validate command reports missing tables​

Symptom

php craft ystore/validate outputs errors such as Table 'ystore_orders' does not exist or Missing migration: m230101_000000_....

Cause: Craft's migration runner has not yet applied all yStore migrations. This can happen if the plugin was installed in an unusual order, or if a migration was skipped.

Solution: Run all pending migrations across all plugins:

php craft migrate/all

Then re-run the validator to confirm:

php craft ystore/validate

If specific migrations are still listed as pending, run them individually:

php craft migrate/up --plugin=ystore

API Issues​

GraphQL returns empty results or a 403​

Symptom

GraphQL queries to /api return null, an empty array, or a 403 Forbidden response, even though data exists in the CP.

Cause: The GraphQL schema does not have permission to access yStore types, or the public schema is disabled.

Solution:

  1. Go to Settings → GraphQL → Schemas in the Craft CP.
  2. Open the Public Schema (or whichever schema your client uses).
  3. Scroll to the yStore section and enable the queries and types your frontend needs.
  4. Save the schema.
tip

If you are using a private schema with a token, make sure the Authorization: Bearer <token> header is being sent correctly from your client.

Checkout & Payment Issues​

Payment gateway not showing in checkout​

Symptom

A payment gateway is installed but does not appear as an option during checkout.

Cause 1 — Plugin not fully configured. The gateway plugin is installed but its settings (API keys, sandbox/live mode) have not been saved.

Solution:

  1. Go to yStore → Payment → Gateways in the CP.
  2. Open the gateway and confirm all required fields (API key, secret, webhook URL) are filled in.
  3. Save and test with the Test Connection button if available.

Cause 2 — Sandbox credentials in a live environment (or vice versa). A mismatch between sandbox/live mode in the plugin settings and the actual keys used.

Solution: Double-check that the Mode selector (Sandbox / Live) matches the credentials you have pasted. Sandbox keys will be rejected in live mode and vice versa.

tip

Always test payment gateways using the gateway provider's official test card numbers in sandbox mode before going live.

Shipping methods not appearing in checkout​

Symptom

No shipping methods are offered to the customer during checkout, or only some methods appear.

Cause: The configured shipping zone does not include the customer's address country, so no methods match.

Solution:

  1. Go to yStore → Shipping → Zones in the CP.
  2. Open each zone and verify the Countries list includes the countries you want to ship to.
  3. Confirm at least one shipping rate or method is assigned to each zone.
  4. If you use table rates, verify the weight and destination columns cover the order's weight range and destination country.
tip

Add a catch-all zone (all countries) with a fallback method during development so checkout is never blocked by a missing zone match.

Quick Reference​

SymptomFirst thing to check
Composer 401 errorauth.json credentials and repository URL
Migration failureDB user privileges; run php craft migrate/all
No yStore menu in CPSettings → Plugins — is yStore installed and enabled?
Validate reports missing tablesRun php craft migrate/up --plugin=ystore
GraphQL returns emptySettings → GraphQL → Schemas — enable yStore types
Payment gateway missingyStore → Payment → Gateways — complete the configuration
No shipping methodsyStore → Shipping → Zones — check country coverage