Unknown attribute: "pingCount" after restoring database dump

[Colton127]

👟 Reproduction steps

1. Create a fresh installation of Appwrite (issue occurs on both 1.8.0 and 1.7.4). Be sure to use same installation config (SSL key) from existing installation.
2. Follow this guide to restore docker volumes and database: https://appwrite.io/blog/post/how-to-back-up-your-appwrite-data
3. Use the ping endpoint on a project. Everything works as expected.
4. Run the migration command, or manually flush redis cache (The migration command flushes redis cache automatically)
5. Now, using the ping endpoint will return a 500 internal server error.

This issue is perhaps best demonstrated using this terminal output:

Appwrite installed successfully
root@aw:~# cd appwrite
root@aw:~/appwrite# docker compose exec -T mariadb sh -c 'exec mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD"' < dump_full.sql
root@aw:~/appwrite# curl --head -H "X-Appwrite-Project: 6482321089e7fc625f5f" http://127.0.0.1/v1/ping/
HTTP/1.1 200 OK
root@aw:~/appwrite# docker exec -it appwrite-redis redis-cli FLUSHALL
OK
root@aw:~/appwrite# curl --head -H "X-Appwrite-Project: 6482321089e7fc625f5f" http://127.0.0.1/v1/ping/
HTTP/1.1 500 Internal Server Error

(Where dump_full.sql is a database dump from a previous installation, and 6482321089e7fc625f5f is a project ID in the database).

The error appears unrecoverable. Recreating the containers, running the migration command again, etc., does not fix the issue.

👍 Expected behavior

Using the ping endpoint or updating project "services" (in project settings) should return 200 OK

👎 Actual Behavior

Using the ping endpoint throws:

[Error] Timestamp: 2025-11-12T21:43:13+00:00
[Error] Method: GET
[Error] URL: /v1/ping
[Error] Type: Utopia\Database\Exception\Structure
[Error] Message: Invalid document structure: Unknown attribute: "pingCount"
[Error] File: /usr/src/code/vendor/utopia-php/database/src/Database/Database.php
[Error] Line: 4271

Similarly, updating the "services" in project settings throws:

[Error] Timestamp: 2025-11-12T21:49:14+00:00
[Error] Method: PATCH
[Error] URL: /v1/projects/:projectId/service
[Error] Type: Utopia\Database\Exception\Structure
[Error] Message: Invalid document structure: Unknown attribute: "pingCount"
[Error] File: /usr/src/code/vendor/utopia-php/database/src/Database/Database.php
[Error] Line: 4271

🎲 Appwrite version

Version 1.8.x

💻 Operating system

Linux

🧱 Your Environment

Fresh installation of x86 Ubuntu 24.04.3 LTS. Issue appears on both Appwrite 1.7.4 and 1.8.0.

👀 Have you spent some time to check if this issue has been raised before?

• [x] I checked and didn't find similar issue

🏢 Have you read the Code of Conduct?

• [x] I have read the Code of Conduct

[github-actions[bot]]

🎯 Agentic Issue Triage

After restoring a database dump from a previous Appwrite installation, the system throws "Unknown attribute: pingCount" errors when flushing Redis cache (either manually or via migration command). This appears to be a schema mismatch between the restored database and current version expectations.

(strong)📋 Issue Analysis(/strong)

Type: Bug Report - Data Migration Issue

Component: Databases, Migrations, Platform

Severity: High - Breaks critical functionality after restore, appears unrecoverable

Environment:

• Affects both Appwrite 1.7.4 and 1.8.0
• Fresh Ubuntu 24.04.3 LTS installation
• Occurs during database restoration from backup

Key Observations:

1. Works fine immediately after database restore
2. Breaks after Redis cache flush (manual or via migration)
3. Error is unrecoverable - recreating containers doesn't help
4. Affects /v1/ping endpoint and project settings updates
5. Error suggests missing pingCount attribute in project schema

(strong)🔍 Root Cause Analysis(/strong)

Error Details:

Invalid document structure: Unknown attribute: "pingCount"
File: /usr/src/code/vendor/utopia-php/database/src/Database/Database.php
Line: 4271

Likely Causes:

1. Schema Version Mismatch:

   • pingCount attribute was added in a specific Appwrite version
   • Restored database from older version lacks this attribute
   • Cache masks the problem until flushed

2. Migration Not Running:

   • Database structure not updated during restore
   • Migration command may not detect schema changes
   • Schema definitions cached vs actual database structure mismatch

3. Projects Collection Schema:

   • pingCount is a project-level attribute
   • Not present in restored database schema
   • Code expects attribute that doesn't exist

Why Cache Flush Triggers It:

• Before flush: Cached project document doesn't validate against schema
• After flush: Fresh read from database validates schema
• Validation fails because database lacks pingCount attribute

(strong)🔧 Debugging Strategy(/strong)

Immediate Investigation:

1. Check Project Schema:

   # In MariaDB
   USE appwrite;
   DESCRIBE _1_schema;
   SELECT * FROM _1_schema WHERE _key = 'projects';
   

2. Check Version:

   # What version was the backup from?
   # What version is current installation?
   docker exec appwrite cat /usr/src/code/app/init.php | grep APP_VERSION
   

3. Compare Schemas:

   • Check if pingCount exists in projects collection attributes
   • Compare with fresh 1.8.0 installation schema

4. Review Migration Logs:

   docker logs appwrite-worker-migrations
   

Workaround to Test:

1. Manual Schema Update:

   • Add pingCount attribute to projects collection manually
   • Check if this resolves the issue

2. Force Migration:

   docker exec appwrite php /usr/src/code/app/cli.php migrate
   

(strong)💡 Potential Solutions(/strong)

Short-term Fix:

1. Improve Migration Detection:

   • Ensure migrations run even when restoring from backup
   • Detect schema version mismatches
   • Provide clear error messages about schema updates needed

2. Add Migration Step to Restore Documentation:

   • Update backup/restore guide to explicitly run migrations
   • Add schema validation step after restore

Long-term Fix:

1. Schema Validation on Startup:

   • Validate project schema against expected structure
   • Auto-run migrations if mismatches detected
   • Provide clear error messages with resolution steps

2. Graceful Degradation:

   • Handle missing attributes gracefully
   • Default to 0 for missing pingCount
   • Log warning instead of throwing error

3. Backup/Restore Tooling:

   • Add built-in backup/restore functionality
   • Include schema version in backups
   • Auto-handle migrations during restore

(strong)📚 Resources(/strong)

• Backup Guide (referenced in issue)
• Migrations Documentation
• Database Structure

Code Areas to Review:

• /app/controllers/api/projects.php - Project schema definition
• /app/cli.php migrate command - Migration logic
• Database schema definitions for projects collection
• Cache invalidation logic

(strong)⚡ Immediate Action Items(/strong)

• [ ] Request more information from reporter:
  • What version was the backup created from?
  • Can they share migration logs?
  • Output of projects collection schema query
• [ ] Reproduce issue locally:
  • Create backup on older version
  • Restore to 1.8.0
  • Flush cache and test
• [ ] Check when pingCount was added to schema
• [ ] Review migration logic for attribute additions
• [ ] Test if manual schema update resolves issue
• [ ] Update restore documentation with migration step
• [ ] Add schema validation warnings/errors
• [ ] Consider backward compatibility for missing attributes

(strong)🎯 Priority Assessment(/strong)

High Priority - This affects users migrating or restoring from backups, which is a critical use case. The issue appears unrecoverable without manual intervention, blocking legitimate restoration workflows.

Labels: Keeping existing product / databases, product / migrations, sdk / cli. Consider adding:

• bug (if not already present)
• upgrade (schema migration issue)
• product / self-hosted (affects self-hosted deployments)

---

Workaround for Reporter (Experimental):

Try manually adding the missing attribute:

1. Identify the current projects collection schema
2. Add pingCount attribute to collection if missing
3. Rerun migration: docker exec appwrite php /usr/src/code/app/cli.php migrate

Note: This needs validation from the Appwrite team before attempting.

AI generated by Agentic Triage

To add this workflow in your repository, run gh aw add githubnext/agentics/workflows/issue-triage.md@0837fb7b24c3b84ee77fb7c8cfa8735c48be347a. See usage guide.

AI generated by Agentic Triage

To add this workflow in your repository, run gh aw add githubnext/agentics/workflows/issue-triage.md@0837fb7b24c3b84ee77fb7c8cfa8735c48be347a. See usage guide.

[roo12312]

+1 facing the same issue

[Error] Type: Utopia\Database\Exception\Structure

[Error] Message: Invalid document structure: Unknown attribute: "pingCount"

[Error] File: /usr/src/code/vendor/utopia-php/database/src/Database/Database.php

[Error] Line: 4271

i had to comment this line

      if (!$structureValidator->isValid($document)) { // Make sure updated
                # throw new StructureException($structureValidator->getDescripti
            }   

to access my appwrite

[ooye-sanket]

Hi everyone

I analyzed the error and it seems like the restored project documents are missing the pingCount attribute that newer Appwrite versions expect. When Redis cache is flushed, the structure validator loads the schema fresh and rejects older documents because the new attribute isn’t present.

Proposed fix direction:

Update the migration for projects to automatically add pingCount with a default value when importing / restoring old data

Alternatively, adjust the structure validator to tolerate missing optional attributes introduced in later versions (backward-compatible)

I can work on a PR for this if this approach looks correct to the maintainers.

Let me know if this direction aligns with the expected fix and I’ll proceed.

[lucasctd]

were you able to fix this?

[Colton127]

were you able to fix this?

No, I had to modify "Validator/Structure.php" to ignore pingCount and pingedAt during validation.

Hi everyone

I analyzed the error and it seems like the restored project documents are missing the pingCount attribute that newer Appwrite versions expect. When Redis cache is flushed, the structure validator loads the schema fresh and rejects older documents because the new attribute isn’t present.

Proposed fix direction:

Update the migration for projects to automatically add pingCount with a default value when importing / restoring old data

Alternatively, adjust the structure validator to tolerate missing optional attributes introduced in later versions (backward-compatible)

I can work on a PR for this if this approach looks correct to the maintainers.

Let me know if this direction aligns with the expected fix and I’ll proceed.

I spent a lot of time debugging this issue, to the point of dumping the database of a clean 1.8 Appwrite database and comparing the values. To my understanding, the issue is not missing attributes. In my database, pingCount exists where it should. The issue arises in the validation itself.

Specifically, the pingCount/pingedAt attributes were added in a later release of Appwrite. The migration tool adds these attributes to existing projects correctly. However, the database validator loads a "template" for the previous Appwrite release before these attributes existed. When it sees the pingCount attribute, it throws an error because it does not recognize it.

Message: Invalid document structure: Unknown attribute: "pingCount"

The error is arising from database validator not recognizing the attribute correctly. The attribute is there correctly. That's why using the latest validator (before flushing redis cache) works without issue.

[Adityakk9031]

please assign it to me pr is ready